|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 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 * # CategoryRender
|
|
|
24 *
|
|
|
25 * Header file for SDL 2D rendering functions.
|
|
|
26 *
|
|
|
27 * This API supports the following features:
|
|
|
28 *
|
|
|
29 * - single pixel points
|
|
|
30 * - single pixel lines
|
|
|
31 * - filled rectangles
|
|
|
32 * - texture images
|
|
|
33 * - 2D polygons
|
|
|
34 *
|
|
|
35 * The primitives may be drawn in opaque, blended, or additive modes.
|
|
|
36 *
|
|
|
37 * The texture images may be drawn in opaque, blended, or additive modes. They
|
|
|
38 * can have an additional color tint or alpha modulation applied to them, and
|
|
|
39 * may also be stretched with linear interpolation.
|
|
|
40 *
|
|
|
41 * This API is designed to accelerate simple 2D operations. You may want more
|
|
|
42 * functionality such as 3D polygons and particle effects, and in that case
|
|
|
43 * you should use SDL's OpenGL/Direct3D support, the SDL3 GPU API, or one of
|
|
|
44 * the many good 3D engines.
|
|
|
45 *
|
|
|
46 * These functions must be called from the main thread. See this bug for
|
|
|
47 * details: https://github.com/libsdl-org/SDL/issues/986
|
|
|
48 */
|
|
|
49
|
|
|
50 #ifndef SDL_render_h_
|
|
|
51 #define SDL_render_h_
|
|
|
52
|
|
|
53 #include <SDL3/SDL_stdinc.h>
|
|
|
54 #include <SDL3/SDL_blendmode.h>
|
|
|
55 #include <SDL3/SDL_error.h>
|
|
|
56 #include <SDL3/SDL_events.h>
|
|
|
57 #include <SDL3/SDL_pixels.h>
|
|
|
58 #include <SDL3/SDL_properties.h>
|
|
|
59 #include <SDL3/SDL_rect.h>
|
|
|
60 #include <SDL3/SDL_surface.h>
|
|
|
61 #include <SDL3/SDL_video.h>
|
|
|
62 #include <SDL3/SDL_gpu.h>
|
|
|
63
|
|
|
64 #include <SDL3/SDL_begin_code.h>
|
|
|
65 /* Set up for C function definitions, even when using C++ */
|
|
|
66 #ifdef __cplusplus
|
|
|
67 extern "C" {
|
|
|
68 #endif
|
|
|
69
|
|
|
70 /**
|
|
|
71 * The name of the software renderer.
|
|
|
72 *
|
|
|
73 * \since This macro is available since SDL 3.2.0.
|
|
|
74 */
|
|
|
75 #define SDL_SOFTWARE_RENDERER "software"
|
|
|
76
|
|
|
77 /**
|
|
|
78 * The name of the GPU renderer.
|
|
|
79 *
|
|
|
80 * \since This macro is available since SDL 3.4.0.
|
|
|
81 */
|
|
|
82 #define SDL_GPU_RENDERER "gpu"
|
|
|
83
|
|
|
84 /**
|
|
|
85 * Vertex structure.
|
|
|
86 *
|
|
|
87 * \since This struct is available since SDL 3.2.0.
|
|
|
88 */
|
|
|
89 typedef struct SDL_Vertex
|
|
|
90 {
|
|
|
91 SDL_FPoint position; /**< Vertex position, in SDL_Renderer coordinates */
|
|
|
92 SDL_FColor color; /**< Vertex color */
|
|
|
93 SDL_FPoint tex_coord; /**< Normalized texture coordinates, if needed */
|
|
|
94 } SDL_Vertex;
|
|
|
95
|
|
|
96 /**
|
|
|
97 * The access pattern allowed for a texture.
|
|
|
98 *
|
|
|
99 * \since This enum is available since SDL 3.2.0.
|
|
|
100 */
|
|
|
101 typedef enum SDL_TextureAccess
|
|
|
102 {
|
|
|
103 SDL_TEXTUREACCESS_STATIC, /**< Changes rarely, not lockable */
|
|
|
104 SDL_TEXTUREACCESS_STREAMING, /**< Changes frequently, lockable */
|
|
|
105 SDL_TEXTUREACCESS_TARGET /**< Texture can be used as a render target */
|
|
|
106 } SDL_TextureAccess;
|
|
|
107
|
|
|
108 /**
|
|
|
109 * The addressing mode for a texture when used in SDL_RenderGeometry().
|
|
|
110 *
|
|
|
111 * This affects how texture coordinates are interpreted outside of [0, 1]
|
|
|
112 *
|
|
|
113 * Texture wrapping is always supported for power of two texture sizes, and is
|
|
|
114 * supported for other texture sizes if
|
|
|
115 * SDL_PROP_RENDERER_TEXTURE_WRAPPING_BOOLEAN is set to true.
|
|
|
116 *
|
|
|
117 * \since This enum is available since SDL 3.4.0.
|
|
|
118 */
|
|
|
119 typedef enum SDL_TextureAddressMode
|
|
|
120 {
|
|
|
121 SDL_TEXTURE_ADDRESS_INVALID = -1,
|
|
|
122 SDL_TEXTURE_ADDRESS_AUTO, /**< Wrapping is enabled if texture coordinates are outside [0, 1], this is the default */
|
|
|
123 SDL_TEXTURE_ADDRESS_CLAMP, /**< Texture coordinates are clamped to the [0, 1] range */
|
|
|
124 SDL_TEXTURE_ADDRESS_WRAP /**< The texture is repeated (tiled) */
|
|
|
125 } SDL_TextureAddressMode;
|
|
|
126
|
|
|
127 /**
|
|
|
128 * How the logical size is mapped to the output.
|
|
|
129 *
|
|
|
130 * \since This enum is available since SDL 3.2.0.
|
|
|
131 */
|
|
|
132 typedef enum SDL_RendererLogicalPresentation
|
|
|
133 {
|
|
|
134 SDL_LOGICAL_PRESENTATION_DISABLED, /**< There is no logical size in effect */
|
|
|
135 SDL_LOGICAL_PRESENTATION_STRETCH, /**< The rendered content is stretched to the output resolution */
|
|
|
136 SDL_LOGICAL_PRESENTATION_LETTERBOX, /**< The rendered content is fit to the largest dimension and the other dimension is letterboxed with the clear color */
|
|
|
137 SDL_LOGICAL_PRESENTATION_OVERSCAN, /**< The rendered content is fit to the smallest dimension and the other dimension extends beyond the output bounds */
|
|
|
138 SDL_LOGICAL_PRESENTATION_INTEGER_SCALE /**< The rendered content is scaled up by integer multiples to fit the output resolution */
|
|
|
139 } SDL_RendererLogicalPresentation;
|
|
|
140
|
|
|
141 /**
|
|
|
142 * A structure representing rendering state
|
|
|
143 *
|
|
|
144 * \since This struct is available since SDL 3.2.0.
|
|
|
145 */
|
|
|
146 typedef struct SDL_Renderer SDL_Renderer;
|
|
|
147
|
|
|
148 #ifndef SDL_INTERNAL
|
|
|
149
|
|
|
150 /**
|
|
|
151 * An efficient driver-specific representation of pixel data
|
|
|
152 *
|
|
|
153 * \since This struct is available since SDL 3.2.0.
|
|
|
154 *
|
|
|
155 * \sa SDL_CreateTexture
|
|
|
156 * \sa SDL_CreateTextureFromSurface
|
|
|
157 * \sa SDL_CreateTextureWithProperties
|
|
|
158 * \sa SDL_DestroyTexture
|
|
|
159 */
|
|
|
160 struct SDL_Texture
|
|
|
161 {
|
|
|
162 SDL_PixelFormat format; /**< The format of the texture, read-only */
|
|
|
163 int w; /**< The width of the texture, read-only. */
|
|
|
164 int h; /**< The height of the texture, read-only. */
|
|
|
165
|
|
|
166 int refcount; /**< Application reference count, used when freeing texture */
|
|
|
167 };
|
|
|
168 #endif /* !SDL_INTERNAL */
|
|
|
169
|
|
|
170 typedef struct SDL_Texture SDL_Texture;
|
|
|
171
|
|
|
172 /* Function prototypes */
|
|
|
173
|
|
|
174 /**
|
|
|
175 * Get the number of 2D rendering drivers available for the current display.
|
|
|
176 *
|
|
|
177 * A render driver is a set of code that handles rendering and texture
|
|
|
178 * management on a particular display. Normally there is only one, but some
|
|
|
179 * drivers may have several available with different capabilities.
|
|
|
180 *
|
|
|
181 * There may be none if SDL was compiled without render support.
|
|
|
182 *
|
|
|
183 * \returns the number of built in render drivers.
|
|
|
184 *
|
|
|
185 * \threadsafety It is safe to call this function from any thread.
|
|
|
186 *
|
|
|
187 * \since This function is available since SDL 3.2.0.
|
|
|
188 *
|
|
|
189 * \sa SDL_CreateRenderer
|
|
|
190 * \sa SDL_GetRenderDriver
|
|
|
191 */
|
|
|
192 extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
|
|
|
193
|
|
|
194 /**
|
|
|
195 * Use this function to get the name of a built in 2D rendering driver.
|
|
|
196 *
|
|
|
197 * The list of rendering drivers is given in the order that they are normally
|
|
|
198 * initialized by default; the drivers that seem more reasonable to choose
|
|
|
199 * first (as far as the SDL developers believe) are earlier in the list.
|
|
|
200 *
|
|
|
201 * The names of drivers are all simple, low-ASCII identifiers, like "opengl",
|
|
|
202 * "direct3d12" or "metal". These never have Unicode characters, and are not
|
|
|
203 * meant to be proper names.
|
|
|
204 *
|
|
|
205 * \param index the index of the rendering driver; the value ranges from 0 to
|
|
|
206 * SDL_GetNumRenderDrivers() - 1.
|
|
|
207 * \returns the name of the rendering driver at the requested index, or NULL
|
|
|
208 * if an invalid index was specified.
|
|
|
209 *
|
|
|
210 * \threadsafety It is safe to call this function from any thread.
|
|
|
211 *
|
|
|
212 * \since This function is available since SDL 3.2.0.
|
|
|
213 *
|
|
|
214 * \sa SDL_GetNumRenderDrivers
|
|
|
215 */
|
|
|
216 extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index);
|
|
|
217
|
|
|
218 /**
|
|
|
219 * Create a window and default renderer.
|
|
|
220 *
|
|
|
221 * \param title the title of the window, in UTF-8 encoding.
|
|
|
222 * \param width the width of the window.
|
|
|
223 * \param height the height of the window.
|
|
|
224 * \param window_flags the flags used to create the window (see
|
|
|
225 * SDL_CreateWindow()).
|
|
|
226 * \param window a pointer filled with the window, or NULL on error.
|
|
|
227 * \param renderer a pointer filled with the renderer, or NULL on error.
|
|
|
228 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
229 * information.
|
|
|
230 *
|
|
|
231 * \threadsafety This function should only be called on the main thread.
|
|
|
232 *
|
|
|
233 * \since This function is available since SDL 3.2.0.
|
|
|
234 *
|
|
|
235 * \sa SDL_CreateRenderer
|
|
|
236 * \sa SDL_CreateWindow
|
|
|
237 */
|
|
|
238 extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer);
|
|
|
239
|
|
|
240 /**
|
|
|
241 * Create a 2D rendering context for a window.
|
|
|
242 *
|
|
|
243 * If you want a specific renderer, you can specify its name here. A list of
|
|
|
244 * available renderers can be obtained by calling SDL_GetRenderDriver()
|
|
|
245 * multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you
|
|
|
246 * don't need a specific renderer, specify NULL and SDL will attempt to choose
|
|
|
247 * the best option for you, based on what is available on the user's system.
|
|
|
248 *
|
|
|
249 * If `name` is a comma-separated list, SDL will try each name, in the order
|
|
|
250 * listed, until one succeeds or all of them fail.
|
|
|
251 *
|
|
|
252 * By default the rendering size matches the window size in pixels, but you
|
|
|
253 * can call SDL_SetRenderLogicalPresentation() to change the content size and
|
|
|
254 * scaling options.
|
|
|
255 *
|
|
|
256 * \param window the window where rendering is displayed.
|
|
|
257 * \param name the name of the rendering driver to initialize, or NULL to let
|
|
|
258 * SDL choose one.
|
|
|
259 * \returns a valid rendering context or NULL if there was an error; call
|
|
|
260 * SDL_GetError() for more information.
|
|
|
261 *
|
|
|
262 * \threadsafety This function should only be called on the main thread.
|
|
|
263 *
|
|
|
264 * \since This function is available since SDL 3.2.0.
|
|
|
265 *
|
|
|
266 * \sa SDL_CreateRendererWithProperties
|
|
|
267 * \sa SDL_CreateSoftwareRenderer
|
|
|
268 * \sa SDL_DestroyRenderer
|
|
|
269 * \sa SDL_GetNumRenderDrivers
|
|
|
270 * \sa SDL_GetRenderDriver
|
|
|
271 * \sa SDL_GetRendererName
|
|
|
272 */
|
|
|
273 extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window, const char *name);
|
|
|
274
|
|
|
275 /**
|
|
|
276 * Create a 2D rendering context for a window, with the specified properties.
|
|
|
277 *
|
|
|
278 * These are the supported properties:
|
|
|
279 *
|
|
|
280 * - `SDL_PROP_RENDERER_CREATE_NAME_STRING`: the name of the rendering driver
|
|
|
281 * to use, if a specific one is desired
|
|
|
282 * - `SDL_PROP_RENDERER_CREATE_WINDOW_POINTER`: the window where rendering is
|
|
|
283 * displayed, required if this isn't a software renderer using a surface
|
|
|
284 * - `SDL_PROP_RENDERER_CREATE_SURFACE_POINTER`: the surface where rendering
|
|
|
285 * is displayed, if you want a software renderer without a window
|
|
|
286 * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace
|
|
|
287 * value describing the colorspace for output to the display, defaults to
|
|
|
288 * SDL_COLORSPACE_SRGB. The direct3d11, direct3d12, and metal renderers
|
|
|
289 * support SDL_COLORSPACE_SRGB_LINEAR, which is a linear color space and
|
|
|
290 * supports HDR output. If you select SDL_COLORSPACE_SRGB_LINEAR, drawing
|
|
|
291 * still uses the sRGB colorspace, but values can go beyond 1.0 and float
|
|
|
292 * (linear) format textures can be used for HDR content.
|
|
|
293 * - `SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER`: non-zero if you want
|
|
|
294 * present synchronized with the refresh rate. This property can take any
|
|
|
295 * value that is supported by SDL_SetRenderVSync() for the renderer.
|
|
|
296 *
|
|
|
297 * With the SDL GPU renderer (since SDL 3.4.0):
|
|
|
298 *
|
|
|
299 * - `SDL_PROP_RENDERER_CREATE_GPU_DEVICE_POINTER`: the device to use with the
|
|
|
300 * renderer, optional.
|
|
|
301 * - `SDL_PROP_RENDERER_CREATE_GPU_SHADERS_SPIRV_BOOLEAN`: the app is able to
|
|
|
302 * provide SPIR-V shaders to SDL_GPURenderState, optional.
|
|
|
303 * - `SDL_PROP_RENDERER_CREATE_GPU_SHADERS_DXIL_BOOLEAN`: the app is able to
|
|
|
304 * provide DXIL shaders to SDL_GPURenderState, optional.
|
|
|
305 * - `SDL_PROP_RENDERER_CREATE_GPU_SHADERS_MSL_BOOLEAN`: the app is able to
|
|
|
306 * provide MSL shaders to SDL_GPURenderState, optional.
|
|
|
307 *
|
|
|
308 * With the vulkan renderer:
|
|
|
309 *
|
|
|
310 * - `SDL_PROP_RENDERER_CREATE_VULKAN_INSTANCE_POINTER`: the VkInstance to use
|
|
|
311 * with the renderer, optional.
|
|
|
312 * - `SDL_PROP_RENDERER_CREATE_VULKAN_SURFACE_NUMBER`: the VkSurfaceKHR to use
|
|
|
313 * with the renderer, optional.
|
|
|
314 * - `SDL_PROP_RENDERER_CREATE_VULKAN_PHYSICAL_DEVICE_POINTER`: the
|
|
|
315 * VkPhysicalDevice to use with the renderer, optional.
|
|
|
316 * - `SDL_PROP_RENDERER_CREATE_VULKAN_DEVICE_POINTER`: the VkDevice to use
|
|
|
317 * with the renderer, optional.
|
|
|
318 * - `SDL_PROP_RENDERER_CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER`: the
|
|
|
319 * queue family index used for rendering.
|
|
|
320 * - `SDL_PROP_RENDERER_CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER`: the
|
|
|
321 * queue family index used for presentation.
|
|
|
322 *
|
|
|
323 * \param props the properties to use.
|
|
|
324 * \returns a valid rendering context or NULL if there was an error; call
|
|
|
325 * SDL_GetError() for more information.
|
|
|
326 *
|
|
|
327 * \threadsafety This function should only be called on the main thread.
|
|
|
328 *
|
|
|
329 * \since This function is available since SDL 3.2.0.
|
|
|
330 *
|
|
|
331 * \sa SDL_CreateProperties
|
|
|
332 * \sa SDL_CreateRenderer
|
|
|
333 * \sa SDL_CreateSoftwareRenderer
|
|
|
334 * \sa SDL_DestroyRenderer
|
|
|
335 * \sa SDL_GetRendererName
|
|
|
336 */
|
|
|
337 extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_PropertiesID props);
|
|
|
338
|
|
|
339 #define SDL_PROP_RENDERER_CREATE_NAME_STRING "SDL.renderer.create.name"
|
|
|
340 #define SDL_PROP_RENDERER_CREATE_WINDOW_POINTER "SDL.renderer.create.window"
|
|
|
341 #define SDL_PROP_RENDERER_CREATE_SURFACE_POINTER "SDL.renderer.create.surface"
|
|
|
342 #define SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER "SDL.renderer.create.output_colorspace"
|
|
|
343 #define SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER "SDL.renderer.create.present_vsync"
|
|
|
344 #define SDL_PROP_RENDERER_CREATE_GPU_DEVICE_POINTER "SDL.renderer.create.gpu.device"
|
|
|
345 #define SDL_PROP_RENDERER_CREATE_GPU_SHADERS_SPIRV_BOOLEAN "SDL.renderer.create.gpu.shaders_spirv"
|
|
|
346 #define SDL_PROP_RENDERER_CREATE_GPU_SHADERS_DXIL_BOOLEAN "SDL.renderer.create.gpu.shaders_dxil"
|
|
|
347 #define SDL_PROP_RENDERER_CREATE_GPU_SHADERS_MSL_BOOLEAN "SDL.renderer.create.gpu.shaders_msl"
|
|
|
348 #define SDL_PROP_RENDERER_CREATE_VULKAN_INSTANCE_POINTER "SDL.renderer.create.vulkan.instance"
|
|
|
349 #define SDL_PROP_RENDERER_CREATE_VULKAN_SURFACE_NUMBER "SDL.renderer.create.vulkan.surface"
|
|
|
350 #define SDL_PROP_RENDERER_CREATE_VULKAN_PHYSICAL_DEVICE_POINTER "SDL.renderer.create.vulkan.physical_device"
|
|
|
351 #define SDL_PROP_RENDERER_CREATE_VULKAN_DEVICE_POINTER "SDL.renderer.create.vulkan.device"
|
|
|
352 #define SDL_PROP_RENDERER_CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.create.vulkan.graphics_queue_family_index"
|
|
|
353 #define SDL_PROP_RENDERER_CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.create.vulkan.present_queue_family_index"
|
|
|
354
|
|
|
355 /**
|
|
|
356 * Create a 2D GPU rendering context.
|
|
|
357 *
|
|
|
358 * The GPU device to use is passed in as a parameter. If this is NULL, then a
|
|
|
359 * device will be created normally and can be retrieved using
|
|
|
360 * SDL_GetGPURendererDevice().
|
|
|
361 *
|
|
|
362 * The window to use is passed in as a parameter. If this is NULL, then this
|
|
|
363 * will become an offscreen renderer. In that case, you should call
|
|
|
364 * SDL_SetRenderTarget() to setup rendering to a texture, and then call
|
|
|
365 * SDL_RenderPresent() normally to complete drawing a frame.
|
|
|
366 *
|
|
|
367 * \param device the GPU device to use with the renderer, or NULL to create a
|
|
|
368 * device.
|
|
|
369 * \param window the window where rendering is displayed, or NULL to create an
|
|
|
370 * offscreen renderer.
|
|
|
371 * \returns a valid rendering context or NULL if there was an error; call
|
|
|
372 * SDL_GetError() for more information.
|
|
|
373 *
|
|
|
374 * \threadsafety If this function is called with a valid GPU device, it should
|
|
|
375 * be called on the thread that created the device. If this
|
|
|
376 * function is called with a valid window, it should be called
|
|
|
377 * on the thread that created the window.
|
|
|
378 *
|
|
|
379 * \since This function is available since SDL 3.4.0.
|
|
|
380 *
|
|
|
381 * \sa SDL_CreateRendererWithProperties
|
|
|
382 * \sa SDL_GetGPURendererDevice
|
|
|
383 * \sa SDL_CreateGPUShader
|
|
|
384 * \sa SDL_CreateGPURenderState
|
|
|
385 * \sa SDL_SetGPURenderState
|
|
|
386 */
|
|
|
387 extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateGPURenderer(SDL_GPUDevice *device, SDL_Window *window);
|
|
|
388
|
|
|
389 /**
|
|
|
390 * Return the GPU device used by a renderer.
|
|
|
391 *
|
|
|
392 * \param renderer the rendering context.
|
|
|
393 * \returns the GPU device used by the renderer, or NULL if the renderer is
|
|
|
394 * not a GPU renderer; call SDL_GetError() for more information.
|
|
|
395 *
|
|
|
396 * \threadsafety It is safe to call this function from any thread.
|
|
|
397 *
|
|
|
398 * \since This function is available since SDL 3.4.0.
|
|
|
399 */
|
|
|
400 extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_GetGPURendererDevice(SDL_Renderer *renderer);
|
|
|
401
|
|
|
402 /**
|
|
|
403 * Create a 2D software rendering context for a surface.
|
|
|
404 *
|
|
|
405 * Two other API which can be used to create SDL_Renderer:
|
|
|
406 * SDL_CreateRenderer() and SDL_CreateWindowAndRenderer(). These can _also_
|
|
|
407 * create a software renderer, but they are intended to be used with an
|
|
|
408 * SDL_Window as the final destination and not an SDL_Surface.
|
|
|
409 *
|
|
|
410 * \param surface the SDL_Surface structure representing the surface where
|
|
|
411 * rendering is done.
|
|
|
412 * \returns a valid rendering context or NULL if there was an error; call
|
|
|
413 * SDL_GetError() for more information.
|
|
|
414 *
|
|
|
415 * \threadsafety It is safe to call this function from any thread.
|
|
|
416 *
|
|
|
417 * \since This function is available since SDL 3.2.0.
|
|
|
418 *
|
|
|
419 * \sa SDL_DestroyRenderer
|
|
|
420 */
|
|
|
421 extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface *surface);
|
|
|
422
|
|
|
423 /**
|
|
|
424 * Get the renderer associated with a window.
|
|
|
425 *
|
|
|
426 * \param window the window to query.
|
|
|
427 * \returns the rendering context on success or NULL on failure; call
|
|
|
428 * SDL_GetError() for more information.
|
|
|
429 *
|
|
|
430 * \threadsafety It is safe to call this function from any thread.
|
|
|
431 *
|
|
|
432 * \since This function is available since SDL 3.2.0.
|
|
|
433 */
|
|
|
434 extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window);
|
|
|
435
|
|
|
436 /**
|
|
|
437 * Get the window associated with a renderer.
|
|
|
438 *
|
|
|
439 * \param renderer the renderer to query.
|
|
|
440 * \returns the window on success or NULL on failure; call SDL_GetError() for
|
|
|
441 * more information.
|
|
|
442 *
|
|
|
443 * \threadsafety It is safe to call this function from any thread.
|
|
|
444 *
|
|
|
445 * \since This function is available since SDL 3.2.0.
|
|
|
446 */
|
|
|
447 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer);
|
|
|
448
|
|
|
449 /**
|
|
|
450 * Get the name of a renderer.
|
|
|
451 *
|
|
|
452 * \param renderer the rendering context.
|
|
|
453 * \returns the name of the selected renderer, or NULL on failure; call
|
|
|
454 * SDL_GetError() for more information.
|
|
|
455 *
|
|
|
456 * \threadsafety It is safe to call this function from any thread.
|
|
|
457 *
|
|
|
458 * \since This function is available since SDL 3.2.0.
|
|
|
459 *
|
|
|
460 * \sa SDL_CreateRenderer
|
|
|
461 * \sa SDL_CreateRendererWithProperties
|
|
|
462 */
|
|
|
463 extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *renderer);
|
|
|
464
|
|
|
465 /**
|
|
|
466 * Get the properties associated with a renderer.
|
|
|
467 *
|
|
|
468 * The following read-only properties are provided by SDL:
|
|
|
469 *
|
|
|
470 * - `SDL_PROP_RENDERER_NAME_STRING`: the name of the rendering driver
|
|
|
471 * - `SDL_PROP_RENDERER_WINDOW_POINTER`: the window where rendering is
|
|
|
472 * displayed, if any
|
|
|
473 * - `SDL_PROP_RENDERER_SURFACE_POINTER`: the surface where rendering is
|
|
|
474 * displayed, if this is a software renderer without a window
|
|
|
475 * - `SDL_PROP_RENDERER_VSYNC_NUMBER`: the current vsync setting
|
|
|
476 * - `SDL_PROP_RENDERER_MAX_TEXTURE_SIZE_NUMBER`: the maximum texture width
|
|
|
477 * and height
|
|
|
478 * - `SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`: a (const SDL_PixelFormat *)
|
|
|
479 * array of pixel formats, terminated with SDL_PIXELFORMAT_UNKNOWN,
|
|
|
480 * representing the available texture formats for this renderer.
|
|
|
481 * - `SDL_PROP_RENDERER_TEXTURE_WRAPPING_BOOLEAN`: true if the renderer
|
|
|
482 * supports SDL_TEXTURE_ADDRESS_WRAP on non-power-of-two textures.
|
|
|
483 * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace value
|
|
|
484 * describing the colorspace for output to the display, defaults to
|
|
|
485 * SDL_COLORSPACE_SRGB.
|
|
|
486 * - `SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN`: true if the output colorspace is
|
|
|
487 * SDL_COLORSPACE_SRGB_LINEAR and the renderer is showing on a display with
|
|
|
488 * HDR enabled. This property can change dynamically when
|
|
|
489 * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent.
|
|
|
490 * - `SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the
|
|
|
491 * SDL_COLORSPACE_SRGB_LINEAR colorspace. When HDR is enabled, this value is
|
|
|
492 * automatically multiplied into the color scale. This property can change
|
|
|
493 * dynamically when SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent.
|
|
|
494 * - `SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT`: the additional high dynamic range
|
|
|
495 * that can be displayed, in terms of the SDR white point. When HDR is not
|
|
|
496 * enabled, this will be 1.0. This property can change dynamically when
|
|
|
497 * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent.
|
|
|
498 *
|
|
|
499 * With the direct3d renderer:
|
|
|
500 *
|
|
|
501 * - `SDL_PROP_RENDERER_D3D9_DEVICE_POINTER`: the IDirect3DDevice9 associated
|
|
|
502 * with the renderer
|
|
|
503 *
|
|
|
504 * With the direct3d11 renderer:
|
|
|
505 *
|
|
|
506 * - `SDL_PROP_RENDERER_D3D11_DEVICE_POINTER`: the ID3D11Device associated
|
|
|
507 * with the renderer
|
|
|
508 * - `SDL_PROP_RENDERER_D3D11_SWAPCHAIN_POINTER`: the IDXGISwapChain1
|
|
|
509 * associated with the renderer. This may change when the window is resized.
|
|
|
510 *
|
|
|
511 * With the direct3d12 renderer:
|
|
|
512 *
|
|
|
513 * - `SDL_PROP_RENDERER_D3D12_DEVICE_POINTER`: the ID3D12Device associated
|
|
|
514 * with the renderer
|
|
|
515 * - `SDL_PROP_RENDERER_D3D12_SWAPCHAIN_POINTER`: the IDXGISwapChain4
|
|
|
516 * associated with the renderer.
|
|
|
517 * - `SDL_PROP_RENDERER_D3D12_COMMAND_QUEUE_POINTER`: the ID3D12CommandQueue
|
|
|
518 * associated with the renderer
|
|
|
519 *
|
|
|
520 * With the vulkan renderer:
|
|
|
521 *
|
|
|
522 * - `SDL_PROP_RENDERER_VULKAN_INSTANCE_POINTER`: the VkInstance associated
|
|
|
523 * with the renderer
|
|
|
524 * - `SDL_PROP_RENDERER_VULKAN_SURFACE_NUMBER`: the VkSurfaceKHR associated
|
|
|
525 * with the renderer
|
|
|
526 * - `SDL_PROP_RENDERER_VULKAN_PHYSICAL_DEVICE_POINTER`: the VkPhysicalDevice
|
|
|
527 * associated with the renderer
|
|
|
528 * - `SDL_PROP_RENDERER_VULKAN_DEVICE_POINTER`: the VkDevice associated with
|
|
|
529 * the renderer
|
|
|
530 * - `SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER`: the queue
|
|
|
531 * family index used for rendering
|
|
|
532 * - `SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER`: the queue
|
|
|
533 * family index used for presentation
|
|
|
534 * - `SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER`: the number of
|
|
|
535 * swapchain images, or potential frames in flight, used by the Vulkan
|
|
|
536 * renderer
|
|
|
537 *
|
|
|
538 * With the gpu renderer:
|
|
|
539 *
|
|
|
540 * - `SDL_PROP_RENDERER_GPU_DEVICE_POINTER`: the SDL_GPUDevice associated with
|
|
|
541 * the renderer
|
|
|
542 *
|
|
|
543 * \param renderer the rendering context.
|
|
|
544 * \returns a valid property ID on success or 0 on failure; call
|
|
|
545 * SDL_GetError() for more information.
|
|
|
546 *
|
|
|
547 * \threadsafety It is safe to call this function from any thread.
|
|
|
548 *
|
|
|
549 * \since This function is available since SDL 3.2.0.
|
|
|
550 */
|
|
|
551 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer);
|
|
|
552
|
|
|
553 #define SDL_PROP_RENDERER_NAME_STRING "SDL.renderer.name"
|
|
|
554 #define SDL_PROP_RENDERER_WINDOW_POINTER "SDL.renderer.window"
|
|
|
555 #define SDL_PROP_RENDERER_SURFACE_POINTER "SDL.renderer.surface"
|
|
|
556 #define SDL_PROP_RENDERER_VSYNC_NUMBER "SDL.renderer.vsync"
|
|
|
557 #define SDL_PROP_RENDERER_MAX_TEXTURE_SIZE_NUMBER "SDL.renderer.max_texture_size"
|
|
|
558 #define SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER "SDL.renderer.texture_formats"
|
|
|
559 #define SDL_PROP_RENDERER_TEXTURE_WRAPPING_BOOLEAN "SDL.renderer.texture_wrapping"
|
|
|
560 #define SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER "SDL.renderer.output_colorspace"
|
|
|
561 #define SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN "SDL.renderer.HDR_enabled"
|
|
|
562 #define SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT "SDL.renderer.SDR_white_point"
|
|
|
563 #define SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT "SDL.renderer.HDR_headroom"
|
|
|
564 #define SDL_PROP_RENDERER_D3D9_DEVICE_POINTER "SDL.renderer.d3d9.device"
|
|
|
565 #define SDL_PROP_RENDERER_D3D11_DEVICE_POINTER "SDL.renderer.d3d11.device"
|
|
|
566 #define SDL_PROP_RENDERER_D3D11_SWAPCHAIN_POINTER "SDL.renderer.d3d11.swap_chain"
|
|
|
567 #define SDL_PROP_RENDERER_D3D12_DEVICE_POINTER "SDL.renderer.d3d12.device"
|
|
|
568 #define SDL_PROP_RENDERER_D3D12_SWAPCHAIN_POINTER "SDL.renderer.d3d12.swap_chain"
|
|
|
569 #define SDL_PROP_RENDERER_D3D12_COMMAND_QUEUE_POINTER "SDL.renderer.d3d12.command_queue"
|
|
|
570 #define SDL_PROP_RENDERER_VULKAN_INSTANCE_POINTER "SDL.renderer.vulkan.instance"
|
|
|
571 #define SDL_PROP_RENDERER_VULKAN_SURFACE_NUMBER "SDL.renderer.vulkan.surface"
|
|
|
572 #define SDL_PROP_RENDERER_VULKAN_PHYSICAL_DEVICE_POINTER "SDL.renderer.vulkan.physical_device"
|
|
|
573 #define SDL_PROP_RENDERER_VULKAN_DEVICE_POINTER "SDL.renderer.vulkan.device"
|
|
|
574 #define SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.graphics_queue_family_index"
|
|
|
575 #define SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.present_queue_family_index"
|
|
|
576 #define SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER "SDL.renderer.vulkan.swapchain_image_count"
|
|
|
577 #define SDL_PROP_RENDERER_GPU_DEVICE_POINTER "SDL.renderer.gpu.device"
|
|
|
578
|
|
|
579 /**
|
|
|
580 * Get the output size in pixels of a rendering context.
|
|
|
581 *
|
|
|
582 * This returns the true output size in pixels, ignoring any render targets or
|
|
|
583 * logical size and presentation.
|
|
|
584 *
|
|
|
585 * For the output size of the current rendering target, with logical size
|
|
|
586 * adjustments, use SDL_GetCurrentRenderOutputSize() instead.
|
|
|
587 *
|
|
|
588 * \param renderer the rendering context.
|
|
|
589 * \param w a pointer filled in with the width in pixels.
|
|
|
590 * \param h a pointer filled in with the height in pixels.
|
|
|
591 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
592 * information.
|
|
|
593 *
|
|
|
594 * \threadsafety This function should only be called on the main thread.
|
|
|
595 *
|
|
|
596 * \since This function is available since SDL 3.2.0.
|
|
|
597 *
|
|
|
598 * \sa SDL_GetCurrentRenderOutputSize
|
|
|
599 */
|
|
|
600 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h);
|
|
|
601
|
|
|
602 /**
|
|
|
603 * Get the current output size in pixels of a rendering context.
|
|
|
604 *
|
|
|
605 * If a rendering target is active, this will return the size of the rendering
|
|
|
606 * target in pixels, otherwise return the value of SDL_GetRenderOutputSize().
|
|
|
607 *
|
|
|
608 * Rendering target or not, the output will be adjusted by the current logical
|
|
|
609 * presentation state, dictated by SDL_SetRenderLogicalPresentation().
|
|
|
610 *
|
|
|
611 * \param renderer the rendering context.
|
|
|
612 * \param w a pointer filled in with the current width.
|
|
|
613 * \param h a pointer filled in with the current height.
|
|
|
614 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
615 * information.
|
|
|
616 *
|
|
|
617 * \threadsafety This function should only be called on the main thread.
|
|
|
618 *
|
|
|
619 * \since This function is available since SDL 3.2.0.
|
|
|
620 *
|
|
|
621 * \sa SDL_GetRenderOutputSize
|
|
|
622 */
|
|
|
623 extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h);
|
|
|
624
|
|
|
625 /**
|
|
|
626 * Create a texture for a rendering context.
|
|
|
627 *
|
|
|
628 * The contents of a texture when first created are not defined.
|
|
|
629 *
|
|
|
630 * \param renderer the rendering context.
|
|
|
631 * \param format one of the enumerated values in SDL_PixelFormat.
|
|
|
632 * \param access one of the enumerated values in SDL_TextureAccess.
|
|
|
633 * \param w the width of the texture in pixels.
|
|
|
634 * \param h the height of the texture in pixels.
|
|
|
635 * \returns the created texture or NULL on failure; call SDL_GetError() for
|
|
|
636 * more information.
|
|
|
637 *
|
|
|
638 * \threadsafety This function should only be called on the main thread.
|
|
|
639 *
|
|
|
640 * \since This function is available since SDL 3.2.0.
|
|
|
641 *
|
|
|
642 * \sa SDL_CreateTextureFromSurface
|
|
|
643 * \sa SDL_CreateTextureWithProperties
|
|
|
644 * \sa SDL_DestroyTexture
|
|
|
645 * \sa SDL_GetTextureSize
|
|
|
646 * \sa SDL_UpdateTexture
|
|
|
647 */
|
|
|
648 extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer *renderer, SDL_PixelFormat format, SDL_TextureAccess access, int w, int h);
|
|
|
649
|
|
|
650 /**
|
|
|
651 * Create a texture from an existing surface.
|
|
|
652 *
|
|
|
653 * The surface is not modified or freed by this function.
|
|
|
654 *
|
|
|
655 * The SDL_TextureAccess hint for the created texture is
|
|
|
656 * `SDL_TEXTUREACCESS_STATIC`.
|
|
|
657 *
|
|
|
658 * The pixel format of the created texture may be different from the pixel
|
|
|
659 * format of the surface, and can be queried using the
|
|
|
660 * SDL_PROP_TEXTURE_FORMAT_NUMBER property.
|
|
|
661 *
|
|
|
662 * \param renderer the rendering context.
|
|
|
663 * \param surface the SDL_Surface structure containing pixel data used to fill
|
|
|
664 * the texture.
|
|
|
665 * \returns the created texture or NULL on failure; call SDL_GetError() for
|
|
|
666 * more information.
|
|
|
667 *
|
|
|
668 * \threadsafety This function should only be called on the main thread.
|
|
|
669 *
|
|
|
670 * \since This function is available since SDL 3.2.0.
|
|
|
671 *
|
|
|
672 * \sa SDL_CreateTexture
|
|
|
673 * \sa SDL_CreateTextureWithProperties
|
|
|
674 * \sa SDL_DestroyTexture
|
|
|
675 */
|
|
|
676 extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *renderer, SDL_Surface *surface);
|
|
|
677
|
|
|
678 /**
|
|
|
679 * Create a texture for a rendering context with the specified properties.
|
|
|
680 *
|
|
|
681 * These are the supported properties:
|
|
|
682 *
|
|
|
683 * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_Colorspace value
|
|
|
684 * describing the texture colorspace, defaults to SDL_COLORSPACE_SRGB_LINEAR
|
|
|
685 * for floating point textures, SDL_COLORSPACE_HDR10 for 10-bit textures,
|
|
|
686 * SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for
|
|
|
687 * YUV textures.
|
|
|
688 * - `SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER`: one of the enumerated values in
|
|
|
689 * SDL_PixelFormat, defaults to the best RGBA format for the renderer
|
|
|
690 * - `SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER`: one of the enumerated values in
|
|
|
691 * SDL_TextureAccess, defaults to SDL_TEXTUREACCESS_STATIC
|
|
|
692 * - `SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER`: the width of the texture in
|
|
|
693 * pixels, required
|
|
|
694 * - `SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER`: the height of the texture in
|
|
|
695 * pixels, required
|
|
|
696 * - `SDL_PROP_TEXTURE_CREATE_PALETTE_POINTER`: an SDL_Palette to use with
|
|
|
697 * palettized texture formats. This can be set later with
|
|
|
698 * SDL_SetTexturePalette()
|
|
|
699 * - `SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT`: for HDR10 and floating
|
|
|
700 * point textures, this defines the value of 100% diffuse white, with higher
|
|
|
701 * values being displayed in the High Dynamic Range headroom. This defaults
|
|
|
702 * to 100 for HDR10 textures and 1.0 for floating point textures.
|
|
|
703 * - `SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT`: for HDR10 and floating
|
|
|
704 * point textures, this defines the maximum dynamic range used by the
|
|
|
705 * content, in terms of the SDR white point. This would be equivalent to
|
|
|
706 * maxCLL / SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT for HDR10 content.
|
|
|
707 * If this is defined, any values outside the range supported by the display
|
|
|
708 * will be scaled into the available HDR headroom, otherwise they are
|
|
|
709 * clipped.
|
|
|
710 *
|
|
|
711 * With the direct3d11 renderer:
|
|
|
712 *
|
|
|
713 * - `SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER`: the ID3D11Texture2D
|
|
|
714 * associated with the texture, if you want to wrap an existing texture.
|
|
|
715 * - `SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER`: the ID3D11Texture2D
|
|
|
716 * associated with the U plane of a YUV texture, if you want to wrap an
|
|
|
717 * existing texture.
|
|
|
718 * - `SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER`: the ID3D11Texture2D
|
|
|
719 * associated with the V plane of a YUV texture, if you want to wrap an
|
|
|
720 * existing texture.
|
|
|
721 *
|
|
|
722 * With the direct3d12 renderer:
|
|
|
723 *
|
|
|
724 * - `SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER`: the ID3D12Resource
|
|
|
725 * associated with the texture, if you want to wrap an existing texture.
|
|
|
726 * - `SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER`: the ID3D12Resource
|
|
|
727 * associated with the U plane of a YUV texture, if you want to wrap an
|
|
|
728 * existing texture.
|
|
|
729 * - `SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER`: the ID3D12Resource
|
|
|
730 * associated with the V plane of a YUV texture, if you want to wrap an
|
|
|
731 * existing texture.
|
|
|
732 *
|
|
|
733 * With the metal renderer:
|
|
|
734 *
|
|
|
735 * - `SDL_PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER`: the CVPixelBufferRef
|
|
|
736 * associated with the texture, if you want to create a texture from an
|
|
|
737 * existing pixel buffer.
|
|
|
738 *
|
|
|
739 * With the opengl renderer:
|
|
|
740 *
|
|
|
741 * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER`: the GLuint texture
|
|
|
742 * associated with the texture, if you want to wrap an existing texture.
|
|
|
743 * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER`: the GLuint texture
|
|
|
744 * associated with the UV plane of an NV12 texture, if you want to wrap an
|
|
|
745 * existing texture.
|
|
|
746 * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER`: the GLuint texture
|
|
|
747 * associated with the U plane of a YUV texture, if you want to wrap an
|
|
|
748 * existing texture.
|
|
|
749 * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER`: the GLuint texture
|
|
|
750 * associated with the V plane of a YUV texture, if you want to wrap an
|
|
|
751 * existing texture.
|
|
|
752 *
|
|
|
753 * With the opengles2 renderer:
|
|
|
754 *
|
|
|
755 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture
|
|
|
756 * associated with the texture, if you want to wrap an existing texture.
|
|
|
757 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture
|
|
|
758 * associated with the texture, if you want to wrap an existing texture.
|
|
|
759 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER`: the GLuint texture
|
|
|
760 * associated with the UV plane of an NV12 texture, if you want to wrap an
|
|
|
761 * existing texture.
|
|
|
762 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER`: the GLuint texture
|
|
|
763 * associated with the U plane of a YUV texture, if you want to wrap an
|
|
|
764 * existing texture.
|
|
|
765 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER`: the GLuint texture
|
|
|
766 * associated with the V plane of a YUV texture, if you want to wrap an
|
|
|
767 * existing texture.
|
|
|
768 *
|
|
|
769 * With the vulkan renderer:
|
|
|
770 *
|
|
|
771 * - `SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER`: the VkImage associated
|
|
|
772 * with the texture, if you want to wrap an existing texture.
|
|
|
773 * - `SDL_PROP_TEXTURE_CREATE_VULKAN_LAYOUT_NUMBER`: the VkImageLayout for the
|
|
|
774 * VkImage, defaults to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL.
|
|
|
775 *
|
|
|
776 * With the GPU renderer:
|
|
|
777 *
|
|
|
778 * - `SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_POINTER`: the SDL_GPUTexture
|
|
|
779 * associated with the texture, if you want to wrap an existing texture.
|
|
|
780 * - `SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_UV_NUMBER`: the SDL_GPUTexture
|
|
|
781 * associated with the UV plane of an NV12 texture, if you want to wrap an
|
|
|
782 * existing texture.
|
|
|
783 * - `SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_U_NUMBER`: the SDL_GPUTexture
|
|
|
784 * associated with the U plane of a YUV texture, if you want to wrap an
|
|
|
785 * existing texture.
|
|
|
786 * - `SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_V_NUMBER`: the SDL_GPUTexture
|
|
|
787 * associated with the V plane of a YUV texture, if you want to wrap an
|
|
|
788 * existing texture.
|
|
|
789 *
|
|
|
790 * \param renderer the rendering context.
|
|
|
791 * \param props the properties to use.
|
|
|
792 * \returns the created texture or NULL on failure; call SDL_GetError() for
|
|
|
793 * more information.
|
|
|
794 *
|
|
|
795 * \threadsafety This function should only be called on the main thread.
|
|
|
796 *
|
|
|
797 * \since This function is available since SDL 3.2.0.
|
|
|
798 *
|
|
|
799 * \sa SDL_CreateProperties
|
|
|
800 * \sa SDL_CreateTexture
|
|
|
801 * \sa SDL_CreateTextureFromSurface
|
|
|
802 * \sa SDL_DestroyTexture
|
|
|
803 * \sa SDL_GetTextureSize
|
|
|
804 * \sa SDL_UpdateTexture
|
|
|
805 */
|
|
|
806 extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Renderer *renderer, SDL_PropertiesID props);
|
|
|
807
|
|
|
808 #define SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER "SDL.texture.create.colorspace"
|
|
|
809 #define SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER "SDL.texture.create.format"
|
|
|
810 #define SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER "SDL.texture.create.access"
|
|
|
811 #define SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER "SDL.texture.create.width"
|
|
|
812 #define SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER "SDL.texture.create.height"
|
|
|
813 #define SDL_PROP_TEXTURE_CREATE_PALETTE_POINTER "SDL.texture.create.palette"
|
|
|
814 #define SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT "SDL.texture.create.SDR_white_point"
|
|
|
815 #define SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT "SDL.texture.create.HDR_headroom"
|
|
|
816 #define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER "SDL.texture.create.d3d11.texture"
|
|
|
817 #define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER "SDL.texture.create.d3d11.texture_u"
|
|
|
818 #define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER "SDL.texture.create.d3d11.texture_v"
|
|
|
819 #define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER "SDL.texture.create.d3d12.texture"
|
|
|
820 #define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER "SDL.texture.create.d3d12.texture_u"
|
|
|
821 #define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER "SDL.texture.create.d3d12.texture_v"
|
|
|
822 #define SDL_PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER "SDL.texture.create.metal.pixelbuffer"
|
|
|
823 #define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER "SDL.texture.create.opengl.texture"
|
|
|
824 #define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER "SDL.texture.create.opengl.texture_uv"
|
|
|
825 #define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER "SDL.texture.create.opengl.texture_u"
|
|
|
826 #define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER "SDL.texture.create.opengl.texture_v"
|
|
|
827 #define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER "SDL.texture.create.opengles2.texture"
|
|
|
828 #define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER "SDL.texture.create.opengles2.texture_uv"
|
|
|
829 #define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER "SDL.texture.create.opengles2.texture_u"
|
|
|
830 #define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER "SDL.texture.create.opengles2.texture_v"
|
|
|
831 #define SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER "SDL.texture.create.vulkan.texture"
|
|
|
832 #define SDL_PROP_TEXTURE_CREATE_VULKAN_LAYOUT_NUMBER "SDL.texture.create.vulkan.layout"
|
|
|
833 #define SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_POINTER "SDL.texture.create.gpu.texture"
|
|
|
834 #define SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_UV_POINTER "SDL.texture.create.gpu.texture_uv"
|
|
|
835 #define SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_U_POINTER "SDL.texture.create.gpu.texture_u"
|
|
|
836 #define SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_V_POINTER "SDL.texture.create.gpu.texture_v"
|
|
|
837
|
|
|
838 /**
|
|
|
839 * Get the properties associated with a texture.
|
|
|
840 *
|
|
|
841 * The following read-only properties are provided by SDL:
|
|
|
842 *
|
|
|
843 * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_Colorspace value describing
|
|
|
844 * the texture colorspace.
|
|
|
845 * - `SDL_PROP_TEXTURE_FORMAT_NUMBER`: one of the enumerated values in
|
|
|
846 * SDL_PixelFormat.
|
|
|
847 * - `SDL_PROP_TEXTURE_ACCESS_NUMBER`: one of the enumerated values in
|
|
|
848 * SDL_TextureAccess.
|
|
|
849 * - `SDL_PROP_TEXTURE_WIDTH_NUMBER`: the width of the texture in pixels.
|
|
|
850 * - `SDL_PROP_TEXTURE_HEIGHT_NUMBER`: the height of the texture in pixels.
|
|
|
851 * - `SDL_PROP_TEXTURE_SDR_WHITE_POINT_FLOAT`: for HDR10 and floating point
|
|
|
852 * textures, this defines the value of 100% diffuse white, with higher
|
|
|
853 * values being displayed in the High Dynamic Range headroom. This defaults
|
|
|
854 * to 100 for HDR10 textures and 1.0 for other textures.
|
|
|
855 * - `SDL_PROP_TEXTURE_HDR_HEADROOM_FLOAT`: for HDR10 and floating point
|
|
|
856 * textures, this defines the maximum dynamic range used by the content, in
|
|
|
857 * terms of the SDR white point. If this is defined, any values outside the
|
|
|
858 * range supported by the display will be scaled into the available HDR
|
|
|
859 * headroom, otherwise they are clipped. This defaults to 1.0 for SDR
|
|
|
860 * textures, 4.0 for HDR10 textures, and no default for floating point
|
|
|
861 * textures.
|
|
|
862 *
|
|
|
863 * With the direct3d11 renderer:
|
|
|
864 *
|
|
|
865 * - `SDL_PROP_TEXTURE_D3D11_TEXTURE_POINTER`: the ID3D11Texture2D associated
|
|
|
866 * with the texture
|
|
|
867 * - `SDL_PROP_TEXTURE_D3D11_TEXTURE_U_POINTER`: the ID3D11Texture2D
|
|
|
868 * associated with the U plane of a YUV texture
|
|
|
869 * - `SDL_PROP_TEXTURE_D3D11_TEXTURE_V_POINTER`: the ID3D11Texture2D
|
|
|
870 * associated with the V plane of a YUV texture
|
|
|
871 *
|
|
|
872 * With the direct3d12 renderer:
|
|
|
873 *
|
|
|
874 * - `SDL_PROP_TEXTURE_D3D12_TEXTURE_POINTER`: the ID3D12Resource associated
|
|
|
875 * with the texture
|
|
|
876 * - `SDL_PROP_TEXTURE_D3D12_TEXTURE_U_POINTER`: the ID3D12Resource associated
|
|
|
877 * with the U plane of a YUV texture
|
|
|
878 * - `SDL_PROP_TEXTURE_D3D12_TEXTURE_V_POINTER`: the ID3D12Resource associated
|
|
|
879 * with the V plane of a YUV texture
|
|
|
880 *
|
|
|
881 * With the vulkan renderer:
|
|
|
882 *
|
|
|
883 * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the
|
|
|
884 * texture
|
|
|
885 *
|
|
|
886 * With the opengl renderer:
|
|
|
887 *
|
|
|
888 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_NUMBER`: the GLuint texture associated
|
|
|
889 * with the texture
|
|
|
890 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_UV_NUMBER`: the GLuint texture
|
|
|
891 * associated with the UV plane of an NV12 texture
|
|
|
892 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_U_NUMBER`: the GLuint texture associated
|
|
|
893 * with the U plane of a YUV texture
|
|
|
894 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_V_NUMBER`: the GLuint texture associated
|
|
|
895 * with the V plane of a YUV texture
|
|
|
896 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_TARGET_NUMBER`: the GLenum for the
|
|
|
897 * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_RECTANGLE_ARB`, etc)
|
|
|
898 * - `SDL_PROP_TEXTURE_OPENGL_TEX_W_FLOAT`: the texture coordinate width of
|
|
|
899 * the texture (0.0 - 1.0)
|
|
|
900 * - `SDL_PROP_TEXTURE_OPENGL_TEX_H_FLOAT`: the texture coordinate height of
|
|
|
901 * the texture (0.0 - 1.0)
|
|
|
902 *
|
|
|
903 * With the opengles2 renderer:
|
|
|
904 *
|
|
|
905 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture
|
|
|
906 * associated with the texture
|
|
|
907 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER`: the GLuint texture
|
|
|
908 * associated with the UV plane of an NV12 texture
|
|
|
909 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER`: the GLuint texture
|
|
|
910 * associated with the U plane of a YUV texture
|
|
|
911 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_V_NUMBER`: the GLuint texture
|
|
|
912 * associated with the V plane of a YUV texture
|
|
|
913 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER`: the GLenum for the
|
|
|
914 * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_EXTERNAL_OES`, etc)
|
|
|
915 *
|
|
|
916 * With the gpu renderer:
|
|
|
917 *
|
|
|
918 * - `SDL_PROP_TEXTURE_GPU_TEXTURE_POINTER`: the SDL_GPUTexture associated
|
|
|
919 * with the texture
|
|
|
920 * - `SDL_PROP_TEXTURE_GPU_TEXTURE_UV_POINTER`: the SDL_GPUTexture associated
|
|
|
921 * with the UV plane of an NV12 texture
|
|
|
922 * - `SDL_PROP_TEXTURE_GPU_TEXTURE_U_POINTER`: the SDL_GPUTexture associated
|
|
|
923 * with the U plane of a YUV texture
|
|
|
924 * - `SDL_PROP_TEXTURE_GPU_TEXTURE_V_POINTER`: the SDL_GPUTexture associated
|
|
|
925 * with the V plane of a YUV texture
|
|
|
926 *
|
|
|
927 * \param texture the texture to query.
|
|
|
928 * \returns a valid property ID on success or 0 on failure; call
|
|
|
929 * SDL_GetError() for more information.
|
|
|
930 *
|
|
|
931 * \threadsafety It is safe to call this function from any thread.
|
|
|
932 *
|
|
|
933 * \since This function is available since SDL 3.2.0.
|
|
|
934 */
|
|
|
935 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture);
|
|
|
936
|
|
|
937 #define SDL_PROP_TEXTURE_COLORSPACE_NUMBER "SDL.texture.colorspace"
|
|
|
938 #define SDL_PROP_TEXTURE_FORMAT_NUMBER "SDL.texture.format"
|
|
|
939 #define SDL_PROP_TEXTURE_ACCESS_NUMBER "SDL.texture.access"
|
|
|
940 #define SDL_PROP_TEXTURE_WIDTH_NUMBER "SDL.texture.width"
|
|
|
941 #define SDL_PROP_TEXTURE_HEIGHT_NUMBER "SDL.texture.height"
|
|
|
942 #define SDL_PROP_TEXTURE_SDR_WHITE_POINT_FLOAT "SDL.texture.SDR_white_point"
|
|
|
943 #define SDL_PROP_TEXTURE_HDR_HEADROOM_FLOAT "SDL.texture.HDR_headroom"
|
|
|
944 #define SDL_PROP_TEXTURE_D3D11_TEXTURE_POINTER "SDL.texture.d3d11.texture"
|
|
|
945 #define SDL_PROP_TEXTURE_D3D11_TEXTURE_U_POINTER "SDL.texture.d3d11.texture_u"
|
|
|
946 #define SDL_PROP_TEXTURE_D3D11_TEXTURE_V_POINTER "SDL.texture.d3d11.texture_v"
|
|
|
947 #define SDL_PROP_TEXTURE_D3D12_TEXTURE_POINTER "SDL.texture.d3d12.texture"
|
|
|
948 #define SDL_PROP_TEXTURE_D3D12_TEXTURE_U_POINTER "SDL.texture.d3d12.texture_u"
|
|
|
949 #define SDL_PROP_TEXTURE_D3D12_TEXTURE_V_POINTER "SDL.texture.d3d12.texture_v"
|
|
|
950 #define SDL_PROP_TEXTURE_OPENGL_TEXTURE_NUMBER "SDL.texture.opengl.texture"
|
|
|
951 #define SDL_PROP_TEXTURE_OPENGL_TEXTURE_UV_NUMBER "SDL.texture.opengl.texture_uv"
|
|
|
952 #define SDL_PROP_TEXTURE_OPENGL_TEXTURE_U_NUMBER "SDL.texture.opengl.texture_u"
|
|
|
953 #define SDL_PROP_TEXTURE_OPENGL_TEXTURE_V_NUMBER "SDL.texture.opengl.texture_v"
|
|
|
954 #define SDL_PROP_TEXTURE_OPENGL_TEXTURE_TARGET_NUMBER "SDL.texture.opengl.target"
|
|
|
955 #define SDL_PROP_TEXTURE_OPENGL_TEX_W_FLOAT "SDL.texture.opengl.tex_w"
|
|
|
956 #define SDL_PROP_TEXTURE_OPENGL_TEX_H_FLOAT "SDL.texture.opengl.tex_h"
|
|
|
957 #define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_NUMBER "SDL.texture.opengles2.texture"
|
|
|
958 #define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER "SDL.texture.opengles2.texture_uv"
|
|
|
959 #define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER "SDL.texture.opengles2.texture_u"
|
|
|
960 #define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_V_NUMBER "SDL.texture.opengles2.texture_v"
|
|
|
961 #define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER "SDL.texture.opengles2.target"
|
|
|
962 #define SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER "SDL.texture.vulkan.texture"
|
|
|
963 #define SDL_PROP_TEXTURE_GPU_TEXTURE_POINTER "SDL.texture.gpu.texture"
|
|
|
964 #define SDL_PROP_TEXTURE_GPU_TEXTURE_UV_POINTER "SDL.texture.gpu.texture_uv"
|
|
|
965 #define SDL_PROP_TEXTURE_GPU_TEXTURE_U_POINTER "SDL.texture.gpu.texture_u"
|
|
|
966 #define SDL_PROP_TEXTURE_GPU_TEXTURE_V_POINTER "SDL.texture.gpu.texture_v"
|
|
|
967
|
|
|
968 /**
|
|
|
969 * Get the renderer that created an SDL_Texture.
|
|
|
970 *
|
|
|
971 * \param texture the texture to query.
|
|
|
972 * \returns a pointer to the SDL_Renderer that created the texture, or NULL on
|
|
|
973 * failure; call SDL_GetError() for more information.
|
|
|
974 *
|
|
|
975 * \threadsafety It is safe to call this function from any thread.
|
|
|
976 *
|
|
|
977 * \since This function is available since SDL 3.2.0.
|
|
|
978 */
|
|
|
979 extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Texture *texture);
|
|
|
980
|
|
|
981 /**
|
|
|
982 * Get the size of a texture, as floating point values.
|
|
|
983 *
|
|
|
984 * \param texture the texture to query.
|
|
|
985 * \param w a pointer filled in with the width of the texture in pixels. This
|
|
|
986 * argument can be NULL if you don't need this information.
|
|
|
987 * \param h a pointer filled in with the height of the texture in pixels. This
|
|
|
988 * argument can be NULL if you don't need this information.
|
|
|
989 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
990 * information.
|
|
|
991 *
|
|
|
992 * \threadsafety This function should only be called on the main thread.
|
|
|
993 *
|
|
|
994 * \since This function is available since SDL 3.2.0.
|
|
|
995 */
|
|
|
996 extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h);
|
|
|
997
|
|
|
998 /**
|
|
|
999 * Set the palette used by a texture.
|
|
|
1000 *
|
|
|
1001 * Setting the palette keeps an internal reference to the palette, which can
|
|
|
1002 * be safely destroyed afterwards.
|
|
|
1003 *
|
|
|
1004 * A single palette can be shared with many textures.
|
|
|
1005 *
|
|
|
1006 * \param texture the texture to update.
|
|
|
1007 * \param palette the SDL_Palette structure to use.
|
|
|
1008 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1009 * information.
|
|
|
1010 *
|
|
|
1011 * \threadsafety This function should only be called on the main thread.
|
|
|
1012 *
|
|
|
1013 * \since This function is available since SDL 3.4.0.
|
|
|
1014 *
|
|
|
1015 * \sa SDL_CreatePalette
|
|
|
1016 * \sa SDL_GetTexturePalette
|
|
|
1017 */
|
|
|
1018 extern SDL_DECLSPEC bool SDLCALL SDL_SetTexturePalette(SDL_Texture *texture, SDL_Palette *palette);
|
|
|
1019
|
|
|
1020 /**
|
|
|
1021 * Get the palette used by a texture.
|
|
|
1022 *
|
|
|
1023 * \param texture the texture to query.
|
|
|
1024 * \returns a pointer to the palette used by the texture, or NULL if there is
|
|
|
1025 * no palette used.
|
|
|
1026 *
|
|
|
1027 * \threadsafety This function should only be called on the main thread.
|
|
|
1028 *
|
|
|
1029 * \since This function is available since SDL 3.4.0.
|
|
|
1030 *
|
|
|
1031 * \sa SDL_SetTexturePalette
|
|
|
1032 */
|
|
|
1033 extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetTexturePalette(SDL_Texture *texture);
|
|
|
1034
|
|
|
1035 /**
|
|
|
1036 * Set an additional color value multiplied into render copy operations.
|
|
|
1037 *
|
|
|
1038 * When this texture is rendered, during the copy operation each source color
|
|
|
1039 * channel is modulated by the appropriate color value according to the
|
|
|
1040 * following formula:
|
|
|
1041 *
|
|
|
1042 * `srcC = srcC * (color / 255)`
|
|
|
1043 *
|
|
|
1044 * Color modulation is not always supported by the renderer; it will return
|
|
|
1045 * false if color modulation is not supported.
|
|
|
1046 *
|
|
|
1047 * \param texture the texture to update.
|
|
|
1048 * \param r the red color value multiplied into copy operations.
|
|
|
1049 * \param g the green color value multiplied into copy operations.
|
|
|
1050 * \param b the blue color value multiplied into copy operations.
|
|
|
1051 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1052 * information.
|
|
|
1053 *
|
|
|
1054 * \threadsafety This function should only be called on the main thread.
|
|
|
1055 *
|
|
|
1056 * \since This function is available since SDL 3.2.0.
|
|
|
1057 *
|
|
|
1058 * \sa SDL_GetTextureColorMod
|
|
|
1059 * \sa SDL_SetTextureAlphaMod
|
|
|
1060 * \sa SDL_SetTextureColorModFloat
|
|
|
1061 */
|
|
|
1062 extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b);
|
|
|
1063
|
|
|
1064
|
|
|
1065 /**
|
|
|
1066 * Set an additional color value multiplied into render copy operations.
|
|
|
1067 *
|
|
|
1068 * When this texture is rendered, during the copy operation each source color
|
|
|
1069 * channel is modulated by the appropriate color value according to the
|
|
|
1070 * following formula:
|
|
|
1071 *
|
|
|
1072 * `srcC = srcC * color`
|
|
|
1073 *
|
|
|
1074 * Color modulation is not always supported by the renderer; it will return
|
|
|
1075 * false if color modulation is not supported.
|
|
|
1076 *
|
|
|
1077 * \param texture the texture to update.
|
|
|
1078 * \param r the red color value multiplied into copy operations.
|
|
|
1079 * \param g the green color value multiplied into copy operations.
|
|
|
1080 * \param b the blue color value multiplied into copy operations.
|
|
|
1081 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1082 * information.
|
|
|
1083 *
|
|
|
1084 * \threadsafety This function should only be called on the main thread.
|
|
|
1085 *
|
|
|
1086 * \since This function is available since SDL 3.2.0.
|
|
|
1087 *
|
|
|
1088 * \sa SDL_GetTextureColorModFloat
|
|
|
1089 * \sa SDL_SetTextureAlphaModFloat
|
|
|
1090 * \sa SDL_SetTextureColorMod
|
|
|
1091 */
|
|
|
1092 extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b);
|
|
|
1093
|
|
|
1094
|
|
|
1095 /**
|
|
|
1096 * Get the additional color value multiplied into render copy operations.
|
|
|
1097 *
|
|
|
1098 * \param texture the texture to query.
|
|
|
1099 * \param r a pointer filled in with the current red color value.
|
|
|
1100 * \param g a pointer filled in with the current green color value.
|
|
|
1101 * \param b a pointer filled in with the current blue color value.
|
|
|
1102 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1103 * information.
|
|
|
1104 *
|
|
|
1105 * \threadsafety This function should only be called on the main thread.
|
|
|
1106 *
|
|
|
1107 * \since This function is available since SDL 3.2.0.
|
|
|
1108 *
|
|
|
1109 * \sa SDL_GetTextureAlphaMod
|
|
|
1110 * \sa SDL_GetTextureColorModFloat
|
|
|
1111 * \sa SDL_SetTextureColorMod
|
|
|
1112 */
|
|
|
1113 extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b);
|
|
|
1114
|
|
|
1115 /**
|
|
|
1116 * Get the additional color value multiplied into render copy operations.
|
|
|
1117 *
|
|
|
1118 * \param texture the texture to query.
|
|
|
1119 * \param r a pointer filled in with the current red color value.
|
|
|
1120 * \param g a pointer filled in with the current green color value.
|
|
|
1121 * \param b a pointer filled in with the current blue color value.
|
|
|
1122 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1123 * information.
|
|
|
1124 *
|
|
|
1125 * \threadsafety This function should only be called on the main thread.
|
|
|
1126 *
|
|
|
1127 * \since This function is available since SDL 3.2.0.
|
|
|
1128 *
|
|
|
1129 * \sa SDL_GetTextureAlphaModFloat
|
|
|
1130 * \sa SDL_GetTextureColorMod
|
|
|
1131 * \sa SDL_SetTextureColorModFloat
|
|
|
1132 */
|
|
|
1133 extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b);
|
|
|
1134
|
|
|
1135 /**
|
|
|
1136 * Set an additional alpha value multiplied into render copy operations.
|
|
|
1137 *
|
|
|
1138 * When this texture is rendered, during the copy operation the source alpha
|
|
|
1139 * value is modulated by this alpha value according to the following formula:
|
|
|
1140 *
|
|
|
1141 * `srcA = srcA * (alpha / 255)`
|
|
|
1142 *
|
|
|
1143 * Alpha modulation is not always supported by the renderer; it will return
|
|
|
1144 * false if alpha modulation is not supported.
|
|
|
1145 *
|
|
|
1146 * \param texture the texture to update.
|
|
|
1147 * \param alpha the source alpha value multiplied into copy operations.
|
|
|
1148 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1149 * information.
|
|
|
1150 *
|
|
|
1151 * \threadsafety This function should only be called on the main thread.
|
|
|
1152 *
|
|
|
1153 * \since This function is available since SDL 3.2.0.
|
|
|
1154 *
|
|
|
1155 * \sa SDL_GetTextureAlphaMod
|
|
|
1156 * \sa SDL_SetTextureAlphaModFloat
|
|
|
1157 * \sa SDL_SetTextureColorMod
|
|
|
1158 */
|
|
|
1159 extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha);
|
|
|
1160
|
|
|
1161 /**
|
|
|
1162 * Set an additional alpha value multiplied into render copy operations.
|
|
|
1163 *
|
|
|
1164 * When this texture is rendered, during the copy operation the source alpha
|
|
|
1165 * value is modulated by this alpha value according to the following formula:
|
|
|
1166 *
|
|
|
1167 * `srcA = srcA * alpha`
|
|
|
1168 *
|
|
|
1169 * Alpha modulation is not always supported by the renderer; it will return
|
|
|
1170 * false if alpha modulation is not supported.
|
|
|
1171 *
|
|
|
1172 * \param texture the texture to update.
|
|
|
1173 * \param alpha the source alpha value multiplied into copy operations.
|
|
|
1174 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1175 * information.
|
|
|
1176 *
|
|
|
1177 * \threadsafety This function should only be called on the main thread.
|
|
|
1178 *
|
|
|
1179 * \since This function is available since SDL 3.2.0.
|
|
|
1180 *
|
|
|
1181 * \sa SDL_GetTextureAlphaModFloat
|
|
|
1182 * \sa SDL_SetTextureAlphaMod
|
|
|
1183 * \sa SDL_SetTextureColorModFloat
|
|
|
1184 */
|
|
|
1185 extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha);
|
|
|
1186
|
|
|
1187 /**
|
|
|
1188 * Get the additional alpha value multiplied into render copy operations.
|
|
|
1189 *
|
|
|
1190 * \param texture the texture to query.
|
|
|
1191 * \param alpha a pointer filled in with the current alpha value.
|
|
|
1192 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1193 * information.
|
|
|
1194 *
|
|
|
1195 * \threadsafety This function should only be called on the main thread.
|
|
|
1196 *
|
|
|
1197 * \since This function is available since SDL 3.2.0.
|
|
|
1198 *
|
|
|
1199 * \sa SDL_GetTextureAlphaModFloat
|
|
|
1200 * \sa SDL_GetTextureColorMod
|
|
|
1201 * \sa SDL_SetTextureAlphaMod
|
|
|
1202 */
|
|
|
1203 extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha);
|
|
|
1204
|
|
|
1205 /**
|
|
|
1206 * Get the additional alpha value multiplied into render copy operations.
|
|
|
1207 *
|
|
|
1208 * \param texture the texture to query.
|
|
|
1209 * \param alpha a pointer filled in with the current alpha value.
|
|
|
1210 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1211 * information.
|
|
|
1212 *
|
|
|
1213 * \threadsafety This function should only be called on the main thread.
|
|
|
1214 *
|
|
|
1215 * \since This function is available since SDL 3.2.0.
|
|
|
1216 *
|
|
|
1217 * \sa SDL_GetTextureAlphaMod
|
|
|
1218 * \sa SDL_GetTextureColorModFloat
|
|
|
1219 * \sa SDL_SetTextureAlphaModFloat
|
|
|
1220 */
|
|
|
1221 extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha);
|
|
|
1222
|
|
|
1223 /**
|
|
|
1224 * Set the blend mode for a texture, used by SDL_RenderTexture().
|
|
|
1225 *
|
|
|
1226 * If the blend mode is not supported, the closest supported mode is chosen
|
|
|
1227 * and this function returns false.
|
|
|
1228 *
|
|
|
1229 * \param texture the texture to update.
|
|
|
1230 * \param blendMode the SDL_BlendMode to use for texture blending.
|
|
|
1231 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1232 * information.
|
|
|
1233 *
|
|
|
1234 * \threadsafety This function should only be called on the main thread.
|
|
|
1235 *
|
|
|
1236 * \since This function is available since SDL 3.2.0.
|
|
|
1237 *
|
|
|
1238 * \sa SDL_GetTextureBlendMode
|
|
|
1239 */
|
|
|
1240 extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode);
|
|
|
1241
|
|
|
1242 /**
|
|
|
1243 * Get the blend mode used for texture copy operations.
|
|
|
1244 *
|
|
|
1245 * \param texture the texture to query.
|
|
|
1246 * \param blendMode a pointer filled in with the current SDL_BlendMode.
|
|
|
1247 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1248 * information.
|
|
|
1249 *
|
|
|
1250 * \threadsafety This function should only be called on the main thread.
|
|
|
1251 *
|
|
|
1252 * \since This function is available since SDL 3.2.0.
|
|
|
1253 *
|
|
|
1254 * \sa SDL_SetTextureBlendMode
|
|
|
1255 */
|
|
|
1256 extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode);
|
|
|
1257
|
|
|
1258 /**
|
|
|
1259 * Set the scale mode used for texture scale operations.
|
|
|
1260 *
|
|
|
1261 * The default texture scale mode is SDL_SCALEMODE_LINEAR.
|
|
|
1262 *
|
|
|
1263 * If the scale mode is not supported, the closest supported mode is chosen.
|
|
|
1264 *
|
|
|
1265 * \param texture the texture to update.
|
|
|
1266 * \param scaleMode the SDL_ScaleMode to use for texture scaling.
|
|
|
1267 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1268 * information.
|
|
|
1269 *
|
|
|
1270 * \threadsafety This function should only be called on the main thread.
|
|
|
1271 *
|
|
|
1272 * \since This function is available since SDL 3.2.0.
|
|
|
1273 *
|
|
|
1274 * \sa SDL_GetTextureScaleMode
|
|
|
1275 */
|
|
|
1276 extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode);
|
|
|
1277
|
|
|
1278 /**
|
|
|
1279 * Get the scale mode used for texture scale operations.
|
|
|
1280 *
|
|
|
1281 * \param texture the texture to query.
|
|
|
1282 * \param scaleMode a pointer filled in with the current scale mode.
|
|
|
1283 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1284 * information.
|
|
|
1285 *
|
|
|
1286 * \threadsafety This function should only be called on the main thread.
|
|
|
1287 *
|
|
|
1288 * \since This function is available since SDL 3.2.0.
|
|
|
1289 *
|
|
|
1290 * \sa SDL_SetTextureScaleMode
|
|
|
1291 */
|
|
|
1292 extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode);
|
|
|
1293
|
|
|
1294 /**
|
|
|
1295 * Update the given texture rectangle with new pixel data.
|
|
|
1296 *
|
|
|
1297 * The pixel data must be in the pixel format of the texture, which can be
|
|
|
1298 * queried using the SDL_PROP_TEXTURE_FORMAT_NUMBER property.
|
|
|
1299 *
|
|
|
1300 * This is a fairly slow function, intended for use with static textures that
|
|
|
1301 * do not change often.
|
|
|
1302 *
|
|
|
1303 * If the texture is intended to be updated often, it is preferred to create
|
|
|
1304 * the texture as streaming and use the locking functions referenced below.
|
|
|
1305 * While this function will work with streaming textures, for optimization
|
|
|
1306 * reasons you may not get the pixels back if you lock the texture afterward.
|
|
|
1307 *
|
|
|
1308 * \param texture the texture to update.
|
|
|
1309 * \param rect an SDL_Rect structure representing the area to update, or NULL
|
|
|
1310 * to update the entire texture.
|
|
|
1311 * \param pixels the raw pixel data in the format of the texture.
|
|
|
1312 * \param pitch the number of bytes in a row of pixel data, including padding
|
|
|
1313 * between lines.
|
|
|
1314 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1315 * information.
|
|
|
1316 *
|
|
|
1317 * \threadsafety This function should only be called on the main thread.
|
|
|
1318 *
|
|
|
1319 * \since This function is available since SDL 3.2.0.
|
|
|
1320 *
|
|
|
1321 * \sa SDL_LockTexture
|
|
|
1322 * \sa SDL_UnlockTexture
|
|
|
1323 * \sa SDL_UpdateNVTexture
|
|
|
1324 * \sa SDL_UpdateYUVTexture
|
|
|
1325 */
|
|
|
1326 extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch);
|
|
|
1327
|
|
|
1328 /**
|
|
|
1329 * Update a rectangle within a planar YV12 or IYUV texture with new pixel
|
|
|
1330 * data.
|
|
|
1331 *
|
|
|
1332 * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
|
|
|
1333 * block of Y and U/V planes in the proper order, but this function is
|
|
|
1334 * available if your pixel data is not contiguous.
|
|
|
1335 *
|
|
|
1336 * \param texture the texture to update.
|
|
|
1337 * \param rect a pointer to the rectangle of pixels to update, or NULL to
|
|
|
1338 * update the entire texture.
|
|
|
1339 * \param Yplane the raw pixel data for the Y plane.
|
|
|
1340 * \param Ypitch the number of bytes between rows of pixel data for the Y
|
|
|
1341 * plane.
|
|
|
1342 * \param Uplane the raw pixel data for the U plane.
|
|
|
1343 * \param Upitch the number of bytes between rows of pixel data for the U
|
|
|
1344 * plane.
|
|
|
1345 * \param Vplane the raw pixel data for the V plane.
|
|
|
1346 * \param Vpitch the number of bytes between rows of pixel data for the V
|
|
|
1347 * plane.
|
|
|
1348 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1349 * information.
|
|
|
1350 *
|
|
|
1351 * \threadsafety This function should only be called on the main thread.
|
|
|
1352 *
|
|
|
1353 * \since This function is available since SDL 3.2.0.
|
|
|
1354 *
|
|
|
1355 * \sa SDL_UpdateNVTexture
|
|
|
1356 * \sa SDL_UpdateTexture
|
|
|
1357 */
|
|
|
1358 extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture,
|
|
|
1359 const SDL_Rect *rect,
|
|
|
1360 const Uint8 *Yplane, int Ypitch,
|
|
|
1361 const Uint8 *Uplane, int Upitch,
|
|
|
1362 const Uint8 *Vplane, int Vpitch);
|
|
|
1363
|
|
|
1364 /**
|
|
|
1365 * Update a rectangle within a planar NV12 or NV21 texture with new pixels.
|
|
|
1366 *
|
|
|
1367 * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
|
|
|
1368 * block of NV12/21 planes in the proper order, but this function is available
|
|
|
1369 * if your pixel data is not contiguous.
|
|
|
1370 *
|
|
|
1371 * \param texture the texture to update.
|
|
|
1372 * \param rect a pointer to the rectangle of pixels to update, or NULL to
|
|
|
1373 * update the entire texture.
|
|
|
1374 * \param Yplane the raw pixel data for the Y plane.
|
|
|
1375 * \param Ypitch the number of bytes between rows of pixel data for the Y
|
|
|
1376 * plane.
|
|
|
1377 * \param UVplane the raw pixel data for the UV plane.
|
|
|
1378 * \param UVpitch the number of bytes between rows of pixel data for the UV
|
|
|
1379 * plane.
|
|
|
1380 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1381 * information.
|
|
|
1382 *
|
|
|
1383 * \threadsafety This function should only be called on the main thread.
|
|
|
1384 *
|
|
|
1385 * \since This function is available since SDL 3.2.0.
|
|
|
1386 *
|
|
|
1387 * \sa SDL_UpdateTexture
|
|
|
1388 * \sa SDL_UpdateYUVTexture
|
|
|
1389 */
|
|
|
1390 extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture,
|
|
|
1391 const SDL_Rect *rect,
|
|
|
1392 const Uint8 *Yplane, int Ypitch,
|
|
|
1393 const Uint8 *UVplane, int UVpitch);
|
|
|
1394
|
|
|
1395 /**
|
|
|
1396 * Lock a portion of the texture for **write-only** pixel access.
|
|
|
1397 *
|
|
|
1398 * As an optimization, the pixels made available for editing don't necessarily
|
|
|
1399 * contain the old texture data. This is a write-only operation, and if you
|
|
|
1400 * need to keep a copy of the texture data you should do that at the
|
|
|
1401 * application level.
|
|
|
1402 *
|
|
|
1403 * You must use SDL_UnlockTexture() to unlock the pixels and apply any
|
|
|
1404 * changes.
|
|
|
1405 *
|
|
|
1406 * \param texture the texture to lock for access, which was created with
|
|
|
1407 * `SDL_TEXTUREACCESS_STREAMING`.
|
|
|
1408 * \param rect an SDL_Rect structure representing the area to lock for access;
|
|
|
1409 * NULL to lock the entire texture.
|
|
|
1410 * \param pixels this is filled in with a pointer to the locked pixels,
|
|
|
1411 * appropriately offset by the locked area.
|
|
|
1412 * \param pitch this is filled in with the pitch of the locked pixels; the
|
|
|
1413 * pitch is the length of one row in bytes.
|
|
|
1414 * \returns true on success or false if the texture is not valid or was not
|
|
|
1415 * created with `SDL_TEXTUREACCESS_STREAMING`; call SDL_GetError()
|
|
|
1416 * for more information.
|
|
|
1417 *
|
|
|
1418 * \threadsafety This function should only be called on the main thread.
|
|
|
1419 *
|
|
|
1420 * \since This function is available since SDL 3.2.0.
|
|
|
1421 *
|
|
|
1422 * \sa SDL_LockTextureToSurface
|
|
|
1423 * \sa SDL_UnlockTexture
|
|
|
1424 */
|
|
|
1425 extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture,
|
|
|
1426 const SDL_Rect *rect,
|
|
|
1427 void **pixels, int *pitch);
|
|
|
1428
|
|
|
1429 /**
|
|
|
1430 * Lock a portion of the texture for **write-only** pixel access, and expose
|
|
|
1431 * it as a SDL surface.
|
|
|
1432 *
|
|
|
1433 * Besides providing an SDL_Surface instead of raw pixel data, this function
|
|
|
1434 * operates like SDL_LockTexture.
|
|
|
1435 *
|
|
|
1436 * As an optimization, the pixels made available for editing don't necessarily
|
|
|
1437 * contain the old texture data. This is a write-only operation, and if you
|
|
|
1438 * need to keep a copy of the texture data you should do that at the
|
|
|
1439 * application level.
|
|
|
1440 *
|
|
|
1441 * You must use SDL_UnlockTexture() to unlock the pixels and apply any
|
|
|
1442 * changes.
|
|
|
1443 *
|
|
|
1444 * The returned surface is freed internally after calling SDL_UnlockTexture()
|
|
|
1445 * or SDL_DestroyTexture(). The caller should not free it.
|
|
|
1446 *
|
|
|
1447 * \param texture the texture to lock for access, which must be created with
|
|
|
1448 * `SDL_TEXTUREACCESS_STREAMING`.
|
|
|
1449 * \param rect a pointer to the rectangle to lock for access. If the rect is
|
|
|
1450 * NULL, the entire texture will be locked.
|
|
|
1451 * \param surface a pointer to an SDL surface of size **rect**. Don't assume
|
|
|
1452 * any specific pixel content.
|
|
|
1453 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1454 * information.
|
|
|
1455 *
|
|
|
1456 * \threadsafety This function should only be called on the main thread.
|
|
|
1457 *
|
|
|
1458 * \since This function is available since SDL 3.2.0.
|
|
|
1459 *
|
|
|
1460 * \sa SDL_LockTexture
|
|
|
1461 * \sa SDL_UnlockTexture
|
|
|
1462 */
|
|
|
1463 extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface);
|
|
|
1464
|
|
|
1465 /**
|
|
|
1466 * Unlock a texture, uploading the changes to video memory, if needed.
|
|
|
1467 *
|
|
|
1468 * **Warning**: Please note that SDL_LockTexture() is intended to be
|
|
|
1469 * write-only; it will not guarantee the previous contents of the texture will
|
|
|
1470 * be provided. You must fully initialize any area of a texture that you lock
|
|
|
1471 * before unlocking it, as the pixels might otherwise be uninitialized memory.
|
|
|
1472 *
|
|
|
1473 * Which is to say: locking and immediately unlocking a texture can result in
|
|
|
1474 * corrupted textures, depending on the renderer in use.
|
|
|
1475 *
|
|
|
1476 * \param texture a texture locked by SDL_LockTexture().
|
|
|
1477 *
|
|
|
1478 * \threadsafety This function should only be called on the main thread.
|
|
|
1479 *
|
|
|
1480 * \since This function is available since SDL 3.2.0.
|
|
|
1481 *
|
|
|
1482 * \sa SDL_LockTexture
|
|
|
1483 */
|
|
|
1484 extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture);
|
|
|
1485
|
|
|
1486 /**
|
|
|
1487 * Set a texture as the current rendering target.
|
|
|
1488 *
|
|
|
1489 * The default render target is the window for which the renderer was created.
|
|
|
1490 * To stop rendering to a texture and render to the window again, call this
|
|
|
1491 * function with a NULL `texture`.
|
|
|
1492 *
|
|
|
1493 * Viewport, cliprect, scale, and logical presentation are unique to each
|
|
|
1494 * render target. Get and set functions for these states apply to the current
|
|
|
1495 * render target set by this function, and those states persist on each target
|
|
|
1496 * when the current render target changes.
|
|
|
1497 *
|
|
|
1498 * \param renderer the rendering context.
|
|
|
1499 * \param texture the targeted texture, which must be created with the
|
|
|
1500 * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the
|
|
|
1501 * window instead of a texture.
|
|
|
1502 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1503 * information.
|
|
|
1504 *
|
|
|
1505 * \threadsafety This function should only be called on the main thread.
|
|
|
1506 *
|
|
|
1507 * \since This function is available since SDL 3.2.0.
|
|
|
1508 *
|
|
|
1509 * \sa SDL_GetRenderTarget
|
|
|
1510 */
|
|
|
1511 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture);
|
|
|
1512
|
|
|
1513 /**
|
|
|
1514 * Get the current render target.
|
|
|
1515 *
|
|
|
1516 * The default render target is the window for which the renderer was created,
|
|
|
1517 * and is reported a NULL here.
|
|
|
1518 *
|
|
|
1519 * \param renderer the rendering context.
|
|
|
1520 * \returns the current render target or NULL for the default render target.
|
|
|
1521 *
|
|
|
1522 * \threadsafety This function should only be called on the main thread.
|
|
|
1523 *
|
|
|
1524 * \since This function is available since SDL 3.2.0.
|
|
|
1525 *
|
|
|
1526 * \sa SDL_SetRenderTarget
|
|
|
1527 */
|
|
|
1528 extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer);
|
|
|
1529
|
|
|
1530 /**
|
|
|
1531 * Set a device-independent resolution and presentation mode for rendering.
|
|
|
1532 *
|
|
|
1533 * This function sets the width and height of the logical rendering output.
|
|
|
1534 * The renderer will act as if the current render target is always the
|
|
|
1535 * requested dimensions, scaling to the actual resolution as necessary.
|
|
|
1536 *
|
|
|
1537 * This can be useful for games that expect a fixed size, but would like to
|
|
|
1538 * scale the output to whatever is available, regardless of how a user resizes
|
|
|
1539 * a window, or if the display is high DPI.
|
|
|
1540 *
|
|
|
1541 * Logical presentation can be used with both render target textures and the
|
|
|
1542 * renderer's window; the state is unique to each render target, and this
|
|
|
1543 * function sets the state for the current render target. It might be useful
|
|
|
1544 * to draw to a texture that matches the window dimensions with logical
|
|
|
1545 * presentation enabled, and then draw that texture across the entire window
|
|
|
1546 * with logical presentation disabled. Be careful not to render both with
|
|
|
1547 * logical presentation enabled, however, as this could produce
|
|
|
1548 * double-letterboxing, etc.
|
|
|
1549 *
|
|
|
1550 * You can disable logical coordinates by setting the mode to
|
|
|
1551 * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel
|
|
|
1552 * resolution of the render target; it is safe to toggle logical presentation
|
|
|
1553 * during the rendering of a frame: perhaps most of the rendering is done to
|
|
|
1554 * specific dimensions but to make fonts look sharp, the app turns off logical
|
|
|
1555 * presentation while drawing text, for example.
|
|
|
1556 *
|
|
|
1557 * You can convert coordinates in an event into rendering coordinates using
|
|
|
1558 * SDL_ConvertEventToRenderCoordinates().
|
|
|
1559 *
|
|
|
1560 * \param renderer the rendering context.
|
|
|
1561 * \param w the width of the logical resolution.
|
|
|
1562 * \param h the height of the logical resolution.
|
|
|
1563 * \param mode the presentation mode used.
|
|
|
1564 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1565 * information.
|
|
|
1566 *
|
|
|
1567 * \threadsafety This function should only be called on the main thread.
|
|
|
1568 *
|
|
|
1569 * \since This function is available since SDL 3.2.0.
|
|
|
1570 *
|
|
|
1571 * \sa SDL_ConvertEventToRenderCoordinates
|
|
|
1572 * \sa SDL_GetRenderLogicalPresentation
|
|
|
1573 * \sa SDL_GetRenderLogicalPresentationRect
|
|
|
1574 */
|
|
|
1575 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode);
|
|
|
1576
|
|
|
1577 /**
|
|
|
1578 * Get device independent resolution and presentation mode for rendering.
|
|
|
1579 *
|
|
|
1580 * This function gets the width and height of the logical rendering output, or
|
|
|
1581 * 0 if a logical resolution is not enabled.
|
|
|
1582 *
|
|
|
1583 * Each render target has its own logical presentation state. This function
|
|
|
1584 * gets the state for the current render target.
|
|
|
1585 *
|
|
|
1586 * \param renderer the rendering context.
|
|
|
1587 * \param w an int filled with the logical presentation width.
|
|
|
1588 * \param h an int filled with the logical presentation height.
|
|
|
1589 * \param mode a variable filled with the logical presentation mode being
|
|
|
1590 * used.
|
|
|
1591 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1592 * information.
|
|
|
1593 *
|
|
|
1594 * \threadsafety This function should only be called on the main thread.
|
|
|
1595 *
|
|
|
1596 * \since This function is available since SDL 3.2.0.
|
|
|
1597 *
|
|
|
1598 * \sa SDL_SetRenderLogicalPresentation
|
|
|
1599 */
|
|
|
1600 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode);
|
|
|
1601
|
|
|
1602 /**
|
|
|
1603 * Get the final presentation rectangle for rendering.
|
|
|
1604 *
|
|
|
1605 * This function returns the calculated rectangle used for logical
|
|
|
1606 * presentation, based on the presentation mode and output size. If logical
|
|
|
1607 * presentation is disabled, it will fill the rectangle with the output size,
|
|
|
1608 * in pixels.
|
|
|
1609 *
|
|
|
1610 * Each render target has its own logical presentation state. This function
|
|
|
1611 * gets the rectangle for the current render target.
|
|
|
1612 *
|
|
|
1613 * \param renderer the rendering context.
|
|
|
1614 * \param rect a pointer filled in with the final presentation rectangle, may
|
|
|
1615 * be NULL.
|
|
|
1616 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1617 * information.
|
|
|
1618 *
|
|
|
1619 * \threadsafety This function should only be called on the main thread.
|
|
|
1620 *
|
|
|
1621 * \since This function is available since SDL 3.2.0.
|
|
|
1622 *
|
|
|
1623 * \sa SDL_SetRenderLogicalPresentation
|
|
|
1624 */
|
|
|
1625 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect);
|
|
|
1626
|
|
|
1627 /**
|
|
|
1628 * Get a point in render coordinates when given a point in window coordinates.
|
|
|
1629 *
|
|
|
1630 * This takes into account several states:
|
|
|
1631 *
|
|
|
1632 * - The window dimensions.
|
|
|
1633 * - The logical presentation settings (SDL_SetRenderLogicalPresentation)
|
|
|
1634 * - The scale (SDL_SetRenderScale)
|
|
|
1635 * - The viewport (SDL_SetRenderViewport)
|
|
|
1636 *
|
|
|
1637 * \param renderer the rendering context.
|
|
|
1638 * \param window_x the x coordinate in window coordinates.
|
|
|
1639 * \param window_y the y coordinate in window coordinates.
|
|
|
1640 * \param x a pointer filled with the x coordinate in render coordinates.
|
|
|
1641 * \param y a pointer filled with the y coordinate in render coordinates.
|
|
|
1642 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1643 * information.
|
|
|
1644 *
|
|
|
1645 * \threadsafety This function should only be called on the main thread.
|
|
|
1646 *
|
|
|
1647 * \since This function is available since SDL 3.2.0.
|
|
|
1648 *
|
|
|
1649 * \sa SDL_SetRenderLogicalPresentation
|
|
|
1650 * \sa SDL_SetRenderScale
|
|
|
1651 */
|
|
|
1652 extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y);
|
|
|
1653
|
|
|
1654 /**
|
|
|
1655 * Get a point in window coordinates when given a point in render coordinates.
|
|
|
1656 *
|
|
|
1657 * This takes into account several states:
|
|
|
1658 *
|
|
|
1659 * - The window dimensions.
|
|
|
1660 * - The logical presentation settings (SDL_SetRenderLogicalPresentation)
|
|
|
1661 * - The scale (SDL_SetRenderScale)
|
|
|
1662 * - The viewport (SDL_SetRenderViewport)
|
|
|
1663 *
|
|
|
1664 * \param renderer the rendering context.
|
|
|
1665 * \param x the x coordinate in render coordinates.
|
|
|
1666 * \param y the y coordinate in render coordinates.
|
|
|
1667 * \param window_x a pointer filled with the x coordinate in window
|
|
|
1668 * coordinates.
|
|
|
1669 * \param window_y a pointer filled with the y coordinate in window
|
|
|
1670 * coordinates.
|
|
|
1671 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1672 * information.
|
|
|
1673 *
|
|
|
1674 * \threadsafety This function should only be called on the main thread.
|
|
|
1675 *
|
|
|
1676 * \since This function is available since SDL 3.2.0.
|
|
|
1677 *
|
|
|
1678 * \sa SDL_SetRenderLogicalPresentation
|
|
|
1679 * \sa SDL_SetRenderScale
|
|
|
1680 * \sa SDL_SetRenderViewport
|
|
|
1681 */
|
|
|
1682 extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y);
|
|
|
1683
|
|
|
1684 /**
|
|
|
1685 * Convert the coordinates in an event to render coordinates.
|
|
|
1686 *
|
|
|
1687 * This takes into account several states:
|
|
|
1688 *
|
|
|
1689 * - The window dimensions.
|
|
|
1690 * - The logical presentation settings (SDL_SetRenderLogicalPresentation)
|
|
|
1691 * - The scale (SDL_SetRenderScale)
|
|
|
1692 * - The viewport (SDL_SetRenderViewport)
|
|
|
1693 *
|
|
|
1694 * Various event types are converted with this function: mouse, touch, pen,
|
|
|
1695 * etc.
|
|
|
1696 *
|
|
|
1697 * Touch coordinates are converted from normalized coordinates in the window
|
|
|
1698 * to non-normalized rendering coordinates.
|
|
|
1699 *
|
|
|
1700 * Relative mouse coordinates (xrel and yrel event fields) are _also_
|
|
|
1701 * converted. Applications that do not want these fields converted should use
|
|
|
1702 * SDL_RenderCoordinatesFromWindow() on the specific event fields instead of
|
|
|
1703 * converting the entire event structure.
|
|
|
1704 *
|
|
|
1705 * Once converted, coordinates may be outside the rendering area.
|
|
|
1706 *
|
|
|
1707 * \param renderer the rendering context.
|
|
|
1708 * \param event the event to modify.
|
|
|
1709 * \returns true if the event is converted or doesn't need conversion, or
|
|
|
1710 * false on failure; call SDL_GetError() for more information.
|
|
|
1711 *
|
|
|
1712 * \threadsafety This function should only be called on the main thread.
|
|
|
1713 *
|
|
|
1714 * \since This function is available since SDL 3.2.0.
|
|
|
1715 *
|
|
|
1716 * \sa SDL_RenderCoordinatesFromWindow
|
|
|
1717 */
|
|
|
1718 extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event);
|
|
|
1719
|
|
|
1720 /**
|
|
|
1721 * Set the drawing area for rendering on the current target.
|
|
|
1722 *
|
|
|
1723 * Drawing will clip to this area (separately from any clipping done with
|
|
|
1724 * SDL_SetRenderClipRect), and the top left of the area will become coordinate
|
|
|
1725 * (0, 0) for future drawing commands.
|
|
|
1726 *
|
|
|
1727 * The area's width and height must be >= 0.
|
|
|
1728 *
|
|
|
1729 * Each render target has its own viewport. This function sets the viewport
|
|
|
1730 * for the current render target.
|
|
|
1731 *
|
|
|
1732 * \param renderer the rendering context.
|
|
|
1733 * \param rect the SDL_Rect structure representing the drawing area, or NULL
|
|
|
1734 * to set the viewport to the entire target.
|
|
|
1735 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1736 * information.
|
|
|
1737 *
|
|
|
1738 * \threadsafety This function should only be called on the main thread.
|
|
|
1739 *
|
|
|
1740 * \since This function is available since SDL 3.2.0.
|
|
|
1741 *
|
|
|
1742 * \sa SDL_GetRenderViewport
|
|
|
1743 * \sa SDL_RenderViewportSet
|
|
|
1744 */
|
|
|
1745 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect);
|
|
|
1746
|
|
|
1747 /**
|
|
|
1748 * Get the drawing area for the current target.
|
|
|
1749 *
|
|
|
1750 * Each render target has its own viewport. This function gets the viewport
|
|
|
1751 * for the current render target.
|
|
|
1752 *
|
|
|
1753 * \param renderer the rendering context.
|
|
|
1754 * \param rect an SDL_Rect structure filled in with the current drawing area.
|
|
|
1755 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1756 * information.
|
|
|
1757 *
|
|
|
1758 * \threadsafety This function should only be called on the main thread.
|
|
|
1759 *
|
|
|
1760 * \since This function is available since SDL 3.2.0.
|
|
|
1761 *
|
|
|
1762 * \sa SDL_RenderViewportSet
|
|
|
1763 * \sa SDL_SetRenderViewport
|
|
|
1764 */
|
|
|
1765 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect);
|
|
|
1766
|
|
|
1767 /**
|
|
|
1768 * Return whether an explicit rectangle was set as the viewport.
|
|
|
1769 *
|
|
|
1770 * This is useful if you're saving and restoring the viewport and want to know
|
|
|
1771 * whether you should restore a specific rectangle or NULL.
|
|
|
1772 *
|
|
|
1773 * Each render target has its own viewport. This function checks the viewport
|
|
|
1774 * for the current render target.
|
|
|
1775 *
|
|
|
1776 * \param renderer the rendering context.
|
|
|
1777 * \returns true if the viewport was set to a specific rectangle, or false if
|
|
|
1778 * it was set to NULL (the entire target).
|
|
|
1779 *
|
|
|
1780 * \threadsafety This function should only be called on the main thread.
|
|
|
1781 *
|
|
|
1782 * \since This function is available since SDL 3.2.0.
|
|
|
1783 *
|
|
|
1784 * \sa SDL_GetRenderViewport
|
|
|
1785 * \sa SDL_SetRenderViewport
|
|
|
1786 */
|
|
|
1787 extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer);
|
|
|
1788
|
|
|
1789 /**
|
|
|
1790 * Get the safe area for rendering within the current viewport.
|
|
|
1791 *
|
|
|
1792 * Some devices have portions of the screen which are partially obscured or
|
|
|
1793 * not interactive, possibly due to on-screen controls, curved edges, camera
|
|
|
1794 * notches, TV overscan, etc. This function provides the area of the current
|
|
|
1795 * viewport which is safe to have interactible content. You should continue
|
|
|
1796 * rendering into the rest of the render target, but it should not contain
|
|
|
1797 * visually important or interactible content.
|
|
|
1798 *
|
|
|
1799 * \param renderer the rendering context.
|
|
|
1800 * \param rect a pointer filled in with the area that is safe for interactive
|
|
|
1801 * content.
|
|
|
1802 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1803 * information.
|
|
|
1804 *
|
|
|
1805 * \threadsafety This function should only be called on the main thread.
|
|
|
1806 *
|
|
|
1807 * \since This function is available since SDL 3.2.0.
|
|
|
1808 */
|
|
|
1809 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect);
|
|
|
1810
|
|
|
1811 /**
|
|
|
1812 * Set the clip rectangle for rendering on the specified target.
|
|
|
1813 *
|
|
|
1814 * Each render target has its own clip rectangle. This function sets the
|
|
|
1815 * cliprect for the current render target.
|
|
|
1816 *
|
|
|
1817 * \param renderer the rendering context.
|
|
|
1818 * \param rect an SDL_Rect structure representing the clip area, relative to
|
|
|
1819 * the viewport, or NULL to disable clipping.
|
|
|
1820 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1821 * information.
|
|
|
1822 *
|
|
|
1823 * \threadsafety This function should only be called on the main thread.
|
|
|
1824 *
|
|
|
1825 * \since This function is available since SDL 3.2.0.
|
|
|
1826 *
|
|
|
1827 * \sa SDL_GetRenderClipRect
|
|
|
1828 * \sa SDL_RenderClipEnabled
|
|
|
1829 */
|
|
|
1830 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect);
|
|
|
1831
|
|
|
1832 /**
|
|
|
1833 * Get the clip rectangle for the current target.
|
|
|
1834 *
|
|
|
1835 * Each render target has its own clip rectangle. This function gets the
|
|
|
1836 * cliprect for the current render target.
|
|
|
1837 *
|
|
|
1838 * \param renderer the rendering context.
|
|
|
1839 * \param rect an SDL_Rect structure filled in with the current clipping area
|
|
|
1840 * or an empty rectangle if clipping is disabled.
|
|
|
1841 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1842 * information.
|
|
|
1843 *
|
|
|
1844 * \threadsafety This function should only be called on the main thread.
|
|
|
1845 *
|
|
|
1846 * \since This function is available since SDL 3.2.0.
|
|
|
1847 *
|
|
|
1848 * \sa SDL_RenderClipEnabled
|
|
|
1849 * \sa SDL_SetRenderClipRect
|
|
|
1850 */
|
|
|
1851 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect);
|
|
|
1852
|
|
|
1853 /**
|
|
|
1854 * Get whether clipping is enabled on the given render target.
|
|
|
1855 *
|
|
|
1856 * Each render target has its own clip rectangle. This function checks the
|
|
|
1857 * cliprect for the current render target.
|
|
|
1858 *
|
|
|
1859 * \param renderer the rendering context.
|
|
|
1860 * \returns true if clipping is enabled or false if not; call SDL_GetError()
|
|
|
1861 * for more information.
|
|
|
1862 *
|
|
|
1863 * \threadsafety This function should only be called on the main thread.
|
|
|
1864 *
|
|
|
1865 * \since This function is available since SDL 3.2.0.
|
|
|
1866 *
|
|
|
1867 * \sa SDL_GetRenderClipRect
|
|
|
1868 * \sa SDL_SetRenderClipRect
|
|
|
1869 */
|
|
|
1870 extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer);
|
|
|
1871
|
|
|
1872 /**
|
|
|
1873 * Set the drawing scale for rendering on the current target.
|
|
|
1874 *
|
|
|
1875 * The drawing coordinates are scaled by the x/y scaling factors before they
|
|
|
1876 * are used by the renderer. This allows resolution independent drawing with a
|
|
|
1877 * single coordinate system.
|
|
|
1878 *
|
|
|
1879 * If this results in scaling or subpixel drawing by the rendering backend, it
|
|
|
1880 * will be handled using the appropriate quality hints. For best results use
|
|
|
1881 * integer scaling factors.
|
|
|
1882 *
|
|
|
1883 * Each render target has its own scale. This function sets the scale for the
|
|
|
1884 * current render target.
|
|
|
1885 *
|
|
|
1886 * \param renderer the rendering context.
|
|
|
1887 * \param scaleX the horizontal scaling factor.
|
|
|
1888 * \param scaleY the vertical scaling factor.
|
|
|
1889 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1890 * information.
|
|
|
1891 *
|
|
|
1892 * \threadsafety This function should only be called on the main thread.
|
|
|
1893 *
|
|
|
1894 * \since This function is available since SDL 3.2.0.
|
|
|
1895 *
|
|
|
1896 * \sa SDL_GetRenderScale
|
|
|
1897 */
|
|
|
1898 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY);
|
|
|
1899
|
|
|
1900 /**
|
|
|
1901 * Get the drawing scale for the current target.
|
|
|
1902 *
|
|
|
1903 * Each render target has its own scale. This function gets the scale for the
|
|
|
1904 * current render target.
|
|
|
1905 *
|
|
|
1906 * \param renderer the rendering context.
|
|
|
1907 * \param scaleX a pointer filled in with the horizontal scaling factor.
|
|
|
1908 * \param scaleY a pointer filled in with the vertical scaling factor.
|
|
|
1909 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1910 * information.
|
|
|
1911 *
|
|
|
1912 * \threadsafety This function should only be called on the main thread.
|
|
|
1913 *
|
|
|
1914 * \since This function is available since SDL 3.2.0.
|
|
|
1915 *
|
|
|
1916 * \sa SDL_SetRenderScale
|
|
|
1917 */
|
|
|
1918 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY);
|
|
|
1919
|
|
|
1920 /**
|
|
|
1921 * Set the color used for drawing operations.
|
|
|
1922 *
|
|
|
1923 * Set the color for drawing or filling rectangles, lines, and points, and for
|
|
|
1924 * SDL_RenderClear().
|
|
|
1925 *
|
|
|
1926 * \param renderer the rendering context.
|
|
|
1927 * \param r the red value used to draw on the rendering target.
|
|
|
1928 * \param g the green value used to draw on the rendering target.
|
|
|
1929 * \param b the blue value used to draw on the rendering target.
|
|
|
1930 * \param a the alpha value used to draw on the rendering target; usually
|
|
|
1931 * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to
|
|
|
1932 * specify how the alpha channel is used.
|
|
|
1933 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1934 * information.
|
|
|
1935 *
|
|
|
1936 * \threadsafety This function should only be called on the main thread.
|
|
|
1937 *
|
|
|
1938 * \since This function is available since SDL 3.2.0.
|
|
|
1939 *
|
|
|
1940 * \sa SDL_GetRenderDrawColor
|
|
|
1941 * \sa SDL_SetRenderDrawColorFloat
|
|
|
1942 */
|
|
|
1943 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
|
|
|
1944
|
|
|
1945 /**
|
|
|
1946 * Set the color used for drawing operations (Rect, Line and Clear).
|
|
|
1947 *
|
|
|
1948 * Set the color for drawing or filling rectangles, lines, and points, and for
|
|
|
1949 * SDL_RenderClear().
|
|
|
1950 *
|
|
|
1951 * \param renderer the rendering context.
|
|
|
1952 * \param r the red value used to draw on the rendering target.
|
|
|
1953 * \param g the green value used to draw on the rendering target.
|
|
|
1954 * \param b the blue value used to draw on the rendering target.
|
|
|
1955 * \param a the alpha value used to draw on the rendering target. Use
|
|
|
1956 * SDL_SetRenderDrawBlendMode to specify how the alpha channel is
|
|
|
1957 * used.
|
|
|
1958 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1959 * information.
|
|
|
1960 *
|
|
|
1961 * \threadsafety This function should only be called on the main thread.
|
|
|
1962 *
|
|
|
1963 * \since This function is available since SDL 3.2.0.
|
|
|
1964 *
|
|
|
1965 * \sa SDL_GetRenderDrawColorFloat
|
|
|
1966 * \sa SDL_SetRenderDrawColor
|
|
|
1967 */
|
|
|
1968 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a);
|
|
|
1969
|
|
|
1970 /**
|
|
|
1971 * Get the color used for drawing operations (Rect, Line and Clear).
|
|
|
1972 *
|
|
|
1973 * \param renderer the rendering context.
|
|
|
1974 * \param r a pointer filled in with the red value used to draw on the
|
|
|
1975 * rendering target.
|
|
|
1976 * \param g a pointer filled in with the green value used to draw on the
|
|
|
1977 * rendering target.
|
|
|
1978 * \param b a pointer filled in with the blue value used to draw on the
|
|
|
1979 * rendering target.
|
|
|
1980 * \param a a pointer filled in with the alpha value used to draw on the
|
|
|
1981 * rendering target; usually `SDL_ALPHA_OPAQUE` (255).
|
|
|
1982 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1983 * information.
|
|
|
1984 *
|
|
|
1985 * \threadsafety This function should only be called on the main thread.
|
|
|
1986 *
|
|
|
1987 * \since This function is available since SDL 3.2.0.
|
|
|
1988 *
|
|
|
1989 * \sa SDL_GetRenderDrawColorFloat
|
|
|
1990 * \sa SDL_SetRenderDrawColor
|
|
|
1991 */
|
|
|
1992 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
|
|
|
1993
|
|
|
1994 /**
|
|
|
1995 * Get the color used for drawing operations (Rect, Line and Clear).
|
|
|
1996 *
|
|
|
1997 * \param renderer the rendering context.
|
|
|
1998 * \param r a pointer filled in with the red value used to draw on the
|
|
|
1999 * rendering target.
|
|
|
2000 * \param g a pointer filled in with the green value used to draw on the
|
|
|
2001 * rendering target.
|
|
|
2002 * \param b a pointer filled in with the blue value used to draw on the
|
|
|
2003 * rendering target.
|
|
|
2004 * \param a a pointer filled in with the alpha value used to draw on the
|
|
|
2005 * rendering target.
|
|
|
2006 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2007 * information.
|
|
|
2008 *
|
|
|
2009 * \threadsafety This function should only be called on the main thread.
|
|
|
2010 *
|
|
|
2011 * \since This function is available since SDL 3.2.0.
|
|
|
2012 *
|
|
|
2013 * \sa SDL_SetRenderDrawColorFloat
|
|
|
2014 * \sa SDL_GetRenderDrawColor
|
|
|
2015 */
|
|
|
2016 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a);
|
|
|
2017
|
|
|
2018 /**
|
|
|
2019 * Set the color scale used for render operations.
|
|
|
2020 *
|
|
|
2021 * The color scale is an additional scale multiplied into the pixel color
|
|
|
2022 * value while rendering. This can be used to adjust the brightness of colors
|
|
|
2023 * during HDR rendering, or changing HDR video brightness when playing on an
|
|
|
2024 * SDR display.
|
|
|
2025 *
|
|
|
2026 * The color scale does not affect the alpha channel, only the color
|
|
|
2027 * brightness.
|
|
|
2028 *
|
|
|
2029 * \param renderer the rendering context.
|
|
|
2030 * \param scale the color scale value.
|
|
|
2031 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2032 * information.
|
|
|
2033 *
|
|
|
2034 * \threadsafety This function should only be called on the main thread.
|
|
|
2035 *
|
|
|
2036 * \since This function is available since SDL 3.2.0.
|
|
|
2037 *
|
|
|
2038 * \sa SDL_GetRenderColorScale
|
|
|
2039 */
|
|
|
2040 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale);
|
|
|
2041
|
|
|
2042 /**
|
|
|
2043 * Get the color scale used for render operations.
|
|
|
2044 *
|
|
|
2045 * \param renderer the rendering context.
|
|
|
2046 * \param scale a pointer filled in with the current color scale value.
|
|
|
2047 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2048 * information.
|
|
|
2049 *
|
|
|
2050 * \threadsafety This function should only be called on the main thread.
|
|
|
2051 *
|
|
|
2052 * \since This function is available since SDL 3.2.0.
|
|
|
2053 *
|
|
|
2054 * \sa SDL_SetRenderColorScale
|
|
|
2055 */
|
|
|
2056 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale);
|
|
|
2057
|
|
|
2058 /**
|
|
|
2059 * Set the blend mode used for drawing operations (Fill and Line).
|
|
|
2060 *
|
|
|
2061 * If the blend mode is not supported, the closest supported mode is chosen.
|
|
|
2062 *
|
|
|
2063 * \param renderer the rendering context.
|
|
|
2064 * \param blendMode the SDL_BlendMode to use for blending.
|
|
|
2065 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2066 * information.
|
|
|
2067 *
|
|
|
2068 * \threadsafety This function should only be called on the main thread.
|
|
|
2069 *
|
|
|
2070 * \since This function is available since SDL 3.2.0.
|
|
|
2071 *
|
|
|
2072 * \sa SDL_GetRenderDrawBlendMode
|
|
|
2073 */
|
|
|
2074 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode);
|
|
|
2075
|
|
|
2076 /**
|
|
|
2077 * Get the blend mode used for drawing operations.
|
|
|
2078 *
|
|
|
2079 * \param renderer the rendering context.
|
|
|
2080 * \param blendMode a pointer filled in with the current SDL_BlendMode.
|
|
|
2081 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2082 * information.
|
|
|
2083 *
|
|
|
2084 * \threadsafety This function should only be called on the main thread.
|
|
|
2085 *
|
|
|
2086 * \since This function is available since SDL 3.2.0.
|
|
|
2087 *
|
|
|
2088 * \sa SDL_SetRenderDrawBlendMode
|
|
|
2089 */
|
|
|
2090 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode);
|
|
|
2091
|
|
|
2092 /**
|
|
|
2093 * Clear the current rendering target with the drawing color.
|
|
|
2094 *
|
|
|
2095 * This function clears the entire rendering target, ignoring the viewport and
|
|
|
2096 * the clip rectangle. Note, that clearing will also set/fill all pixels of
|
|
|
2097 * the rendering target to current renderer draw color, so make sure to invoke
|
|
|
2098 * SDL_SetRenderDrawColor() when needed.
|
|
|
2099 *
|
|
|
2100 * \param renderer the rendering context.
|
|
|
2101 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2102 * information.
|
|
|
2103 *
|
|
|
2104 * \threadsafety This function should only be called on the main thread.
|
|
|
2105 *
|
|
|
2106 * \since This function is available since SDL 3.2.0.
|
|
|
2107 *
|
|
|
2108 * \sa SDL_SetRenderDrawColor
|
|
|
2109 */
|
|
|
2110 extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer);
|
|
|
2111
|
|
|
2112 /**
|
|
|
2113 * Draw a point on the current rendering target at subpixel precision.
|
|
|
2114 *
|
|
|
2115 * \param renderer the renderer which should draw a point.
|
|
|
2116 * \param x the x coordinate of the point.
|
|
|
2117 * \param y the y coordinate of the point.
|
|
|
2118 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2119 * information.
|
|
|
2120 *
|
|
|
2121 * \threadsafety This function should only be called on the main thread.
|
|
|
2122 *
|
|
|
2123 * \since This function is available since SDL 3.2.0.
|
|
|
2124 *
|
|
|
2125 * \sa SDL_RenderPoints
|
|
|
2126 */
|
|
|
2127 extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y);
|
|
|
2128
|
|
|
2129 /**
|
|
|
2130 * Draw multiple points on the current rendering target at subpixel precision.
|
|
|
2131 *
|
|
|
2132 * \param renderer the renderer which should draw multiple points.
|
|
|
2133 * \param points the points to draw.
|
|
|
2134 * \param count the number of points to draw.
|
|
|
2135 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2136 * information.
|
|
|
2137 *
|
|
|
2138 * \threadsafety This function should only be called on the main thread.
|
|
|
2139 *
|
|
|
2140 * \since This function is available since SDL 3.2.0.
|
|
|
2141 *
|
|
|
2142 * \sa SDL_RenderPoint
|
|
|
2143 */
|
|
|
2144 extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count);
|
|
|
2145
|
|
|
2146 /**
|
|
|
2147 * Draw a line on the current rendering target at subpixel precision.
|
|
|
2148 *
|
|
|
2149 * \param renderer the renderer which should draw a line.
|
|
|
2150 * \param x1 the x coordinate of the start point.
|
|
|
2151 * \param y1 the y coordinate of the start point.
|
|
|
2152 * \param x2 the x coordinate of the end point.
|
|
|
2153 * \param y2 the y coordinate of the end point.
|
|
|
2154 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2155 * information.
|
|
|
2156 *
|
|
|
2157 * \threadsafety This function should only be called on the main thread.
|
|
|
2158 *
|
|
|
2159 * \since This function is available since SDL 3.2.0.
|
|
|
2160 *
|
|
|
2161 * \sa SDL_RenderLines
|
|
|
2162 */
|
|
|
2163 extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2);
|
|
|
2164
|
|
|
2165 /**
|
|
|
2166 * Draw a series of connected lines on the current rendering target at
|
|
|
2167 * subpixel precision.
|
|
|
2168 *
|
|
|
2169 * \param renderer the renderer which should draw multiple lines.
|
|
|
2170 * \param points the points along the lines.
|
|
|
2171 * \param count the number of points, drawing count-1 lines.
|
|
|
2172 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2173 * information.
|
|
|
2174 *
|
|
|
2175 * \threadsafety This function should only be called on the main thread.
|
|
|
2176 *
|
|
|
2177 * \since This function is available since SDL 3.2.0.
|
|
|
2178 *
|
|
|
2179 * \sa SDL_RenderLine
|
|
|
2180 */
|
|
|
2181 extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count);
|
|
|
2182
|
|
|
2183 /**
|
|
|
2184 * Draw a rectangle on the current rendering target at subpixel precision.
|
|
|
2185 *
|
|
|
2186 * \param renderer the renderer which should draw a rectangle.
|
|
|
2187 * \param rect a pointer to the destination rectangle, or NULL to outline the
|
|
|
2188 * entire rendering target.
|
|
|
2189 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2190 * information.
|
|
|
2191 *
|
|
|
2192 * \threadsafety This function should only be called on the main thread.
|
|
|
2193 *
|
|
|
2194 * \since This function is available since SDL 3.2.0.
|
|
|
2195 *
|
|
|
2196 * \sa SDL_RenderRects
|
|
|
2197 */
|
|
|
2198 extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect);
|
|
|
2199
|
|
|
2200 /**
|
|
|
2201 * Draw some number of rectangles on the current rendering target at subpixel
|
|
|
2202 * precision.
|
|
|
2203 *
|
|
|
2204 * \param renderer the renderer which should draw multiple rectangles.
|
|
|
2205 * \param rects a pointer to an array of destination rectangles.
|
|
|
2206 * \param count the number of rectangles.
|
|
|
2207 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2208 * information.
|
|
|
2209 *
|
|
|
2210 * \threadsafety This function should only be called on the main thread.
|
|
|
2211 *
|
|
|
2212 * \since This function is available since SDL 3.2.0.
|
|
|
2213 *
|
|
|
2214 * \sa SDL_RenderRect
|
|
|
2215 */
|
|
|
2216 extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count);
|
|
|
2217
|
|
|
2218 /**
|
|
|
2219 * Fill a rectangle on the current rendering target with the drawing color at
|
|
|
2220 * subpixel precision.
|
|
|
2221 *
|
|
|
2222 * \param renderer the renderer which should fill a rectangle.
|
|
|
2223 * \param rect a pointer to the destination rectangle, or NULL for the entire
|
|
|
2224 * rendering target.
|
|
|
2225 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2226 * information.
|
|
|
2227 *
|
|
|
2228 * \threadsafety This function should only be called on the main thread.
|
|
|
2229 *
|
|
|
2230 * \since This function is available since SDL 3.2.0.
|
|
|
2231 *
|
|
|
2232 * \sa SDL_RenderFillRects
|
|
|
2233 */
|
|
|
2234 extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect);
|
|
|
2235
|
|
|
2236 /**
|
|
|
2237 * Fill some number of rectangles on the current rendering target with the
|
|
|
2238 * drawing color at subpixel precision.
|
|
|
2239 *
|
|
|
2240 * \param renderer the renderer which should fill multiple rectangles.
|
|
|
2241 * \param rects a pointer to an array of destination rectangles.
|
|
|
2242 * \param count the number of rectangles.
|
|
|
2243 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2244 * information.
|
|
|
2245 *
|
|
|
2246 * \threadsafety This function should only be called on the main thread.
|
|
|
2247 *
|
|
|
2248 * \since This function is available since SDL 3.2.0.
|
|
|
2249 *
|
|
|
2250 * \sa SDL_RenderFillRect
|
|
|
2251 */
|
|
|
2252 extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count);
|
|
|
2253
|
|
|
2254 /**
|
|
|
2255 * Copy a portion of the texture to the current rendering target at subpixel
|
|
|
2256 * precision.
|
|
|
2257 *
|
|
|
2258 * \param renderer the renderer which should copy parts of a texture.
|
|
|
2259 * \param texture the source texture.
|
|
|
2260 * \param srcrect a pointer to the source rectangle, or NULL for the entire
|
|
|
2261 * texture.
|
|
|
2262 * \param dstrect a pointer to the destination rectangle, or NULL for the
|
|
|
2263 * entire rendering target.
|
|
|
2264 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2265 * information.
|
|
|
2266 *
|
|
|
2267 * \threadsafety This function should only be called on the main thread.
|
|
|
2268 *
|
|
|
2269 * \since This function is available since SDL 3.2.0.
|
|
|
2270 *
|
|
|
2271 * \sa SDL_RenderTextureRotated
|
|
|
2272 * \sa SDL_RenderTextureTiled
|
|
|
2273 */
|
|
|
2274 extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect);
|
|
|
2275
|
|
|
2276 /**
|
|
|
2277 * Copy a portion of the source texture to the current rendering target, with
|
|
|
2278 * rotation and flipping, at subpixel precision.
|
|
|
2279 *
|
|
|
2280 * \param renderer the renderer which should copy parts of a texture.
|
|
|
2281 * \param texture the source texture.
|
|
|
2282 * \param srcrect a pointer to the source rectangle, or NULL for the entire
|
|
|
2283 * texture.
|
|
|
2284 * \param dstrect a pointer to the destination rectangle, or NULL for the
|
|
|
2285 * entire rendering target.
|
|
|
2286 * \param angle an angle in degrees that indicates the rotation that will be
|
|
|
2287 * applied to dstrect, rotating it in a clockwise direction.
|
|
|
2288 * \param center a pointer to a point indicating the point around which
|
|
|
2289 * dstrect will be rotated (if NULL, rotation will be done
|
|
|
2290 * around dstrect.w/2, dstrect.h/2).
|
|
|
2291 * \param flip an SDL_FlipMode value stating which flipping actions should be
|
|
|
2292 * performed on the texture.
|
|
|
2293 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2294 * information.
|
|
|
2295 *
|
|
|
2296 * \threadsafety This function should only be called on the main thread.
|
|
|
2297 *
|
|
|
2298 * \since This function is available since SDL 3.2.0.
|
|
|
2299 *
|
|
|
2300 * \sa SDL_RenderTexture
|
|
|
2301 */
|
|
|
2302 extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture,
|
|
|
2303 const SDL_FRect *srcrect, const SDL_FRect *dstrect,
|
|
|
2304 double angle, const SDL_FPoint *center,
|
|
|
2305 SDL_FlipMode flip);
|
|
|
2306
|
|
|
2307 /**
|
|
|
2308 * Copy a portion of the source texture to the current rendering target, with
|
|
|
2309 * affine transform, at subpixel precision.
|
|
|
2310 *
|
|
|
2311 * \param renderer the renderer which should copy parts of a texture.
|
|
|
2312 * \param texture the source texture.
|
|
|
2313 * \param srcrect a pointer to the source rectangle, or NULL for the entire
|
|
|
2314 * texture.
|
|
|
2315 * \param origin a pointer to a point indicating where the top-left corner of
|
|
|
2316 * srcrect should be mapped to, or NULL for the rendering
|
|
|
2317 * target's origin.
|
|
|
2318 * \param right a pointer to a point indicating where the top-right corner of
|
|
|
2319 * srcrect should be mapped to, or NULL for the rendering
|
|
|
2320 * target's top-right corner.
|
|
|
2321 * \param down a pointer to a point indicating where the bottom-left corner of
|
|
|
2322 * srcrect should be mapped to, or NULL for the rendering target's
|
|
|
2323 * bottom-left corner.
|
|
|
2324 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2325 * information.
|
|
|
2326 *
|
|
|
2327 * \threadsafety You may only call this function from the main thread.
|
|
|
2328 *
|
|
|
2329 * \since This function is available since SDL 3.2.0.
|
|
|
2330 *
|
|
|
2331 * \sa SDL_RenderTexture
|
|
|
2332 */
|
|
|
2333 extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureAffine(SDL_Renderer *renderer, SDL_Texture *texture,
|
|
|
2334 const SDL_FRect *srcrect, const SDL_FPoint *origin,
|
|
|
2335 const SDL_FPoint *right, const SDL_FPoint *down);
|
|
|
2336
|
|
|
2337 /**
|
|
|
2338 * Tile a portion of the texture to the current rendering target at subpixel
|
|
|
2339 * precision.
|
|
|
2340 *
|
|
|
2341 * The pixels in `srcrect` will be repeated as many times as needed to
|
|
|
2342 * completely fill `dstrect`.
|
|
|
2343 *
|
|
|
2344 * \param renderer the renderer which should copy parts of a texture.
|
|
|
2345 * \param texture the source texture.
|
|
|
2346 * \param srcrect a pointer to the source rectangle, or NULL for the entire
|
|
|
2347 * texture.
|
|
|
2348 * \param scale the scale used to transform srcrect into the destination
|
|
|
2349 * rectangle, e.g. a 32x32 texture with a scale of 2 would fill
|
|
|
2350 * 64x64 tiles.
|
|
|
2351 * \param dstrect a pointer to the destination rectangle, or NULL for the
|
|
|
2352 * entire rendering target.
|
|
|
2353 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2354 * information.
|
|
|
2355 *
|
|
|
2356 * \threadsafety This function should only be called on the main thread.
|
|
|
2357 *
|
|
|
2358 * \since This function is available since SDL 3.2.0.
|
|
|
2359 *
|
|
|
2360 * \sa SDL_RenderTexture
|
|
|
2361 */
|
|
|
2362 extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect);
|
|
|
2363
|
|
|
2364 /**
|
|
|
2365 * Perform a scaled copy using the 9-grid algorithm to the current rendering
|
|
|
2366 * target at subpixel precision.
|
|
|
2367 *
|
|
|
2368 * The pixels in the texture are split into a 3x3 grid, using the different
|
|
|
2369 * corner sizes for each corner, and the sides and center making up the
|
|
|
2370 * remaining pixels. The corners are then scaled using `scale` and fit into
|
|
|
2371 * the corners of the destination rectangle. The sides and center are then
|
|
|
2372 * stretched into place to cover the remaining destination rectangle.
|
|
|
2373 *
|
|
|
2374 * \param renderer the renderer which should copy parts of a texture.
|
|
|
2375 * \param texture the source texture.
|
|
|
2376 * \param srcrect the SDL_Rect structure representing the rectangle to be used
|
|
|
2377 * for the 9-grid, or NULL to use the entire texture.
|
|
|
2378 * \param left_width the width, in pixels, of the left corners in `srcrect`.
|
|
|
2379 * \param right_width the width, in pixels, of the right corners in `srcrect`.
|
|
|
2380 * \param top_height the height, in pixels, of the top corners in `srcrect`.
|
|
|
2381 * \param bottom_height the height, in pixels, of the bottom corners in
|
|
|
2382 * `srcrect`.
|
|
|
2383 * \param scale the scale used to transform the corner of `srcrect` into the
|
|
|
2384 * corner of `dstrect`, or 0.0f for an unscaled copy.
|
|
|
2385 * \param dstrect a pointer to the destination rectangle, or NULL for the
|
|
|
2386 * entire rendering target.
|
|
|
2387 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2388 * information.
|
|
|
2389 *
|
|
|
2390 * \threadsafety This function should only be called on the main thread.
|
|
|
2391 *
|
|
|
2392 * \since This function is available since SDL 3.2.0.
|
|
|
2393 *
|
|
|
2394 * \sa SDL_RenderTexture
|
|
|
2395 * \sa SDL_RenderTexture9GridTiled
|
|
|
2396 */
|
|
|
2397 extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect);
|
|
|
2398
|
|
|
2399 /**
|
|
|
2400 * Perform a scaled copy using the 9-grid algorithm to the current rendering
|
|
|
2401 * target at subpixel precision.
|
|
|
2402 *
|
|
|
2403 * The pixels in the texture are split into a 3x3 grid, using the different
|
|
|
2404 * corner sizes for each corner, and the sides and center making up the
|
|
|
2405 * remaining pixels. The corners are then scaled using `scale` and fit into
|
|
|
2406 * the corners of the destination rectangle. The sides and center are then
|
|
|
2407 * tiled into place to cover the remaining destination rectangle.
|
|
|
2408 *
|
|
|
2409 * \param renderer the renderer which should copy parts of a texture.
|
|
|
2410 * \param texture the source texture.
|
|
|
2411 * \param srcrect the SDL_Rect structure representing the rectangle to be used
|
|
|
2412 * for the 9-grid, or NULL to use the entire texture.
|
|
|
2413 * \param left_width the width, in pixels, of the left corners in `srcrect`.
|
|
|
2414 * \param right_width the width, in pixels, of the right corners in `srcrect`.
|
|
|
2415 * \param top_height the height, in pixels, of the top corners in `srcrect`.
|
|
|
2416 * \param bottom_height the height, in pixels, of the bottom corners in
|
|
|
2417 * `srcrect`.
|
|
|
2418 * \param scale the scale used to transform the corner of `srcrect` into the
|
|
|
2419 * corner of `dstrect`, or 0.0f for an unscaled copy.
|
|
|
2420 * \param dstrect a pointer to the destination rectangle, or NULL for the
|
|
|
2421 * entire rendering target.
|
|
|
2422 * \param tileScale the scale used to transform the borders and center of
|
|
|
2423 * `srcrect` into the borders and middle of `dstrect`, or
|
|
|
2424 * 1.0f for an unscaled copy.
|
|
|
2425 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2426 * information.
|
|
|
2427 *
|
|
|
2428 * \threadsafety This function should only be called on the main thread.
|
|
|
2429 *
|
|
|
2430 * \since This function is available since SDL 3.4.0.
|
|
|
2431 *
|
|
|
2432 * \sa SDL_RenderTexture
|
|
|
2433 * \sa SDL_RenderTexture9Grid
|
|
|
2434 */
|
|
|
2435 extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9GridTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect, float tileScale);
|
|
|
2436
|
|
|
2437 /**
|
|
|
2438 * Render a list of triangles, optionally using a texture and indices into the
|
|
|
2439 * vertex array Color and alpha modulation is done per vertex
|
|
|
2440 * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored).
|
|
|
2441 *
|
|
|
2442 * \param renderer the rendering context.
|
|
|
2443 * \param texture (optional) The SDL texture to use.
|
|
|
2444 * \param vertices vertices.
|
|
|
2445 * \param num_vertices number of vertices.
|
|
|
2446 * \param indices (optional) An array of integer indices into the 'vertices'
|
|
|
2447 * array, if NULL all vertices will be rendered in sequential
|
|
|
2448 * order.
|
|
|
2449 * \param num_indices number of indices.
|
|
|
2450 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2451 * information.
|
|
|
2452 *
|
|
|
2453 * \threadsafety This function should only be called on the main thread.
|
|
|
2454 *
|
|
|
2455 * \since This function is available since SDL 3.2.0.
|
|
|
2456 *
|
|
|
2457 * \sa SDL_RenderGeometryRaw
|
|
|
2458 * \sa SDL_SetRenderTextureAddressMode
|
|
|
2459 */
|
|
|
2460 extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer,
|
|
|
2461 SDL_Texture *texture,
|
|
|
2462 const SDL_Vertex *vertices, int num_vertices,
|
|
|
2463 const int *indices, int num_indices);
|
|
|
2464
|
|
|
2465 /**
|
|
|
2466 * Render a list of triangles, optionally using a texture and indices into the
|
|
|
2467 * vertex arrays Color and alpha modulation is done per vertex
|
|
|
2468 * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored).
|
|
|
2469 *
|
|
|
2470 * \param renderer the rendering context.
|
|
|
2471 * \param texture (optional) The SDL texture to use.
|
|
|
2472 * \param xy vertex positions.
|
|
|
2473 * \param xy_stride byte size to move from one element to the next element.
|
|
|
2474 * \param color vertex colors (as SDL_FColor).
|
|
|
2475 * \param color_stride byte size to move from one element to the next element.
|
|
|
2476 * \param uv vertex normalized texture coordinates.
|
|
|
2477 * \param uv_stride byte size to move from one element to the next element.
|
|
|
2478 * \param num_vertices number of vertices.
|
|
|
2479 * \param indices (optional) An array of indices into the 'vertices' arrays,
|
|
|
2480 * if NULL all vertices will be rendered in sequential order.
|
|
|
2481 * \param num_indices number of indices.
|
|
|
2482 * \param size_indices index size: 1 (byte), 2 (short), 4 (int).
|
|
|
2483 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2484 * information.
|
|
|
2485 *
|
|
|
2486 * \threadsafety This function should only be called on the main thread.
|
|
|
2487 *
|
|
|
2488 * \since This function is available since SDL 3.2.0.
|
|
|
2489 *
|
|
|
2490 * \sa SDL_RenderGeometry
|
|
|
2491 * \sa SDL_SetRenderTextureAddressMode
|
|
|
2492 */
|
|
|
2493 extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer,
|
|
|
2494 SDL_Texture *texture,
|
|
|
2495 const float *xy, int xy_stride,
|
|
|
2496 const SDL_FColor *color, int color_stride,
|
|
|
2497 const float *uv, int uv_stride,
|
|
|
2498 int num_vertices,
|
|
|
2499 const void *indices, int num_indices, int size_indices);
|
|
|
2500
|
|
|
2501 /**
|
|
|
2502 * Set the texture addressing mode used in SDL_RenderGeometry().
|
|
|
2503 *
|
|
|
2504 * \param renderer the rendering context.
|
|
|
2505 * \param u_mode the SDL_TextureAddressMode to use for horizontal texture
|
|
|
2506 * coordinates in SDL_RenderGeometry().
|
|
|
2507 * \param v_mode the SDL_TextureAddressMode to use for vertical texture
|
|
|
2508 * coordinates in SDL_RenderGeometry().
|
|
|
2509 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2510 * information.
|
|
|
2511 *
|
|
|
2512 * \since This function is available since SDL 3.4.0.
|
|
|
2513 *
|
|
|
2514 * \sa SDL_RenderGeometry
|
|
|
2515 * \sa SDL_RenderGeometryRaw
|
|
|
2516 * \sa SDL_GetRenderTextureAddressMode
|
|
|
2517 */
|
|
|
2518 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTextureAddressMode(SDL_Renderer *renderer, SDL_TextureAddressMode u_mode, SDL_TextureAddressMode v_mode);
|
|
|
2519
|
|
|
2520 /**
|
|
|
2521 * Get the texture addressing mode used in SDL_RenderGeometry().
|
|
|
2522 *
|
|
|
2523 * \param renderer the rendering context.
|
|
|
2524 * \param u_mode a pointer filled in with the SDL_TextureAddressMode to use
|
|
|
2525 * for horizontal texture coordinates in SDL_RenderGeometry(),
|
|
|
2526 * may be NULL.
|
|
|
2527 * \param v_mode a pointer filled in with the SDL_TextureAddressMode to use
|
|
|
2528 * for vertical texture coordinates in SDL_RenderGeometry(), may
|
|
|
2529 * be NULL.
|
|
|
2530 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2531 * information.
|
|
|
2532 *
|
|
|
2533 * \since This function is available since SDL 3.4.0.
|
|
|
2534 *
|
|
|
2535 * \sa SDL_SetRenderTextureAddressMode
|
|
|
2536 */
|
|
|
2537 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderTextureAddressMode(SDL_Renderer *renderer, SDL_TextureAddressMode *u_mode, SDL_TextureAddressMode *v_mode);
|
|
|
2538
|
|
|
2539 /**
|
|
|
2540 * Read pixels from the current rendering target.
|
|
|
2541 *
|
|
|
2542 * The returned surface contains pixels inside the desired area clipped to the
|
|
|
2543 * current viewport, and should be freed with SDL_DestroySurface().
|
|
|
2544 *
|
|
|
2545 * Note that this returns the actual pixels on the screen, so if you are using
|
|
|
2546 * logical presentation you should use SDL_GetRenderLogicalPresentationRect()
|
|
|
2547 * to get the area containing your content.
|
|
|
2548 *
|
|
|
2549 * **WARNING**: This is a very slow operation, and should not be used
|
|
|
2550 * frequently. If you're using this on the main rendering target, it should be
|
|
|
2551 * called after rendering and before SDL_RenderPresent().
|
|
|
2552 *
|
|
|
2553 * \param renderer the rendering context.
|
|
|
2554 * \param rect an SDL_Rect structure representing the area to read, which will
|
|
|
2555 * be clipped to the current viewport, or NULL for the entire
|
|
|
2556 * viewport.
|
|
|
2557 * \returns a new SDL_Surface on success or NULL on failure; call
|
|
|
2558 * SDL_GetError() for more information.
|
|
|
2559 *
|
|
|
2560 * \threadsafety This function should only be called on the main thread.
|
|
|
2561 *
|
|
|
2562 * \since This function is available since SDL 3.2.0.
|
|
|
2563 */
|
|
|
2564 extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect);
|
|
|
2565
|
|
|
2566 /**
|
|
|
2567 * Update the screen with any rendering performed since the previous call.
|
|
|
2568 *
|
|
|
2569 * SDL's rendering functions operate on a backbuffer; that is, calling a
|
|
|
2570 * rendering function such as SDL_RenderLine() does not directly put a line on
|
|
|
2571 * the screen, but rather updates the backbuffer. As such, you compose your
|
|
|
2572 * entire scene and *present* the composed backbuffer to the screen as a
|
|
|
2573 * complete picture.
|
|
|
2574 *
|
|
|
2575 * Therefore, when using SDL's rendering API, one does all drawing intended
|
|
|
2576 * for the frame, and then calls this function once per frame to present the
|
|
|
2577 * final drawing to the user.
|
|
|
2578 *
|
|
|
2579 * The backbuffer should be considered invalidated after each present; do not
|
|
|
2580 * assume that previous contents will exist between frames. You are strongly
|
|
|
2581 * encouraged to call SDL_RenderClear() to initialize the backbuffer before
|
|
|
2582 * starting each new frame's drawing, even if you plan to overwrite every
|
|
|
2583 * pixel.
|
|
|
2584 *
|
|
|
2585 * Please note, that in case of rendering to a texture - there is **no need**
|
|
|
2586 * to call `SDL_RenderPresent` after drawing needed objects to a texture, and
|
|
|
2587 * should not be done; you are only required to change back the rendering
|
|
|
2588 * target to default via `SDL_SetRenderTarget(renderer, NULL)` afterwards, as
|
|
|
2589 * textures by themselves do not have a concept of backbuffers. Calling
|
|
|
2590 * SDL_RenderPresent while rendering to a texture will fail.
|
|
|
2591 *
|
|
|
2592 * \param renderer the rendering context.
|
|
|
2593 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2594 * information.
|
|
|
2595 *
|
|
|
2596 * \threadsafety This function should only be called on the main thread.
|
|
|
2597 *
|
|
|
2598 * \since This function is available since SDL 3.2.0.
|
|
|
2599 *
|
|
|
2600 * \sa SDL_CreateRenderer
|
|
|
2601 * \sa SDL_RenderClear
|
|
|
2602 * \sa SDL_RenderFillRect
|
|
|
2603 * \sa SDL_RenderFillRects
|
|
|
2604 * \sa SDL_RenderLine
|
|
|
2605 * \sa SDL_RenderLines
|
|
|
2606 * \sa SDL_RenderPoint
|
|
|
2607 * \sa SDL_RenderPoints
|
|
|
2608 * \sa SDL_RenderRect
|
|
|
2609 * \sa SDL_RenderRects
|
|
|
2610 * \sa SDL_SetRenderDrawBlendMode
|
|
|
2611 * \sa SDL_SetRenderDrawColor
|
|
|
2612 */
|
|
|
2613 extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer);
|
|
|
2614
|
|
|
2615 /**
|
|
|
2616 * Destroy the specified texture.
|
|
|
2617 *
|
|
|
2618 * Passing NULL or an otherwise invalid texture will set the SDL error message
|
|
|
2619 * to "Invalid texture".
|
|
|
2620 *
|
|
|
2621 * \param texture the texture to destroy.
|
|
|
2622 *
|
|
|
2623 * \threadsafety This function should only be called on the main thread.
|
|
|
2624 *
|
|
|
2625 * \since This function is available since SDL 3.2.0.
|
|
|
2626 *
|
|
|
2627 * \sa SDL_CreateTexture
|
|
|
2628 * \sa SDL_CreateTextureFromSurface
|
|
|
2629 */
|
|
|
2630 extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture);
|
|
|
2631
|
|
|
2632 /**
|
|
|
2633 * Destroy the rendering context for a window and free all associated
|
|
|
2634 * textures.
|
|
|
2635 *
|
|
|
2636 * This should be called before destroying the associated window.
|
|
|
2637 *
|
|
|
2638 * \param renderer the rendering context.
|
|
|
2639 *
|
|
|
2640 * \threadsafety This function should only be called on the main thread.
|
|
|
2641 *
|
|
|
2642 * \since This function is available since SDL 3.2.0.
|
|
|
2643 *
|
|
|
2644 * \sa SDL_CreateRenderer
|
|
|
2645 */
|
|
|
2646 extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer);
|
|
|
2647
|
|
|
2648 /**
|
|
|
2649 * Force the rendering context to flush any pending commands and state.
|
|
|
2650 *
|
|
|
2651 * You do not need to (and in fact, shouldn't) call this function unless you
|
|
|
2652 * are planning to call into OpenGL/Direct3D/Metal/whatever directly, in
|
|
|
2653 * addition to using an SDL_Renderer.
|
|
|
2654 *
|
|
|
2655 * This is for a very-specific case: if you are using SDL's render API, and
|
|
|
2656 * you plan to make OpenGL/D3D/whatever calls in addition to SDL render API
|
|
|
2657 * calls. If this applies, you should call this function between calls to
|
|
|
2658 * SDL's render API and the low-level API you're using in cooperation.
|
|
|
2659 *
|
|
|
2660 * In all other cases, you can ignore this function.
|
|
|
2661 *
|
|
|
2662 * This call makes SDL flush any pending rendering work it was queueing up to
|
|
|
2663 * do later in a single batch, and marks any internal cached state as invalid,
|
|
|
2664 * so it'll prepare all its state again later, from scratch.
|
|
|
2665 *
|
|
|
2666 * This means you do not need to save state in your rendering code to protect
|
|
|
2667 * the SDL renderer. However, there lots of arbitrary pieces of Direct3D and
|
|
|
2668 * OpenGL state that can confuse things; you should use your best judgment and
|
|
|
2669 * be prepared to make changes if specific state needs to be protected.
|
|
|
2670 *
|
|
|
2671 * \param renderer the rendering context.
|
|
|
2672 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2673 * information.
|
|
|
2674 *
|
|
|
2675 * \threadsafety This function should only be called on the main thread.
|
|
|
2676 *
|
|
|
2677 * \since This function is available since SDL 3.2.0.
|
|
|
2678 */
|
|
|
2679 extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer);
|
|
|
2680
|
|
|
2681 /**
|
|
|
2682 * Get the CAMetalLayer associated with the given Metal renderer.
|
|
|
2683 *
|
|
|
2684 * This function returns `void *`, so SDL doesn't have to include Metal's
|
|
|
2685 * headers, but it can be safely cast to a `CAMetalLayer *`.
|
|
|
2686 *
|
|
|
2687 * \param renderer the renderer to query.
|
|
|
2688 * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a
|
|
|
2689 * Metal renderer.
|
|
|
2690 *
|
|
|
2691 * \threadsafety This function should only be called on the main thread.
|
|
|
2692 *
|
|
|
2693 * \since This function is available since SDL 3.2.0.
|
|
|
2694 *
|
|
|
2695 * \sa SDL_GetRenderMetalCommandEncoder
|
|
|
2696 */
|
|
|
2697 extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *renderer);
|
|
|
2698
|
|
|
2699 /**
|
|
|
2700 * Get the Metal command encoder for the current frame.
|
|
|
2701 *
|
|
|
2702 * This function returns `void *`, so SDL doesn't have to include Metal's
|
|
|
2703 * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
|
|
|
2704 *
|
|
|
2705 * This will return NULL if Metal refuses to give SDL a drawable to render to,
|
|
|
2706 * which might happen if the window is hidden/minimized/offscreen. This
|
|
|
2707 * doesn't apply to command encoders for render targets, just the window's
|
|
|
2708 * backbuffer. Check your return values!
|
|
|
2709 *
|
|
|
2710 * \param renderer the renderer to query.
|
|
|
2711 * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the
|
|
|
2712 * renderer isn't a Metal renderer or there was an error.
|
|
|
2713 *
|
|
|
2714 * \threadsafety This function should only be called on the main thread.
|
|
|
2715 *
|
|
|
2716 * \since This function is available since SDL 3.2.0.
|
|
|
2717 *
|
|
|
2718 * \sa SDL_GetRenderMetalLayer
|
|
|
2719 */
|
|
|
2720 extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer *renderer);
|
|
|
2721
|
|
|
2722
|
|
|
2723 /**
|
|
|
2724 * Add a set of synchronization semaphores for the current frame.
|
|
|
2725 *
|
|
|
2726 * The Vulkan renderer will wait for `wait_semaphore` before submitting
|
|
|
2727 * rendering commands and signal `signal_semaphore` after rendering commands
|
|
|
2728 * are complete for this frame.
|
|
|
2729 *
|
|
|
2730 * This should be called each frame that you want semaphore synchronization.
|
|
|
2731 * The Vulkan renderer may have multiple frames in flight on the GPU, so you
|
|
|
2732 * should have multiple semaphores that are used for synchronization. Querying
|
|
|
2733 * SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER will give you the
|
|
|
2734 * maximum number of semaphores you'll need.
|
|
|
2735 *
|
|
|
2736 * \param renderer the rendering context.
|
|
|
2737 * \param wait_stage_mask the VkPipelineStageFlags for the wait.
|
|
|
2738 * \param wait_semaphore a VkSempahore to wait on before rendering the current
|
|
|
2739 * frame, or 0 if not needed.
|
|
|
2740 * \param signal_semaphore a VkSempahore that SDL will signal when rendering
|
|
|
2741 * for the current frame is complete, or 0 if not
|
|
|
2742 * needed.
|
|
|
2743 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2744 * information.
|
|
|
2745 *
|
|
|
2746 * \threadsafety It is **NOT** safe to call this function from two threads at
|
|
|
2747 * once.
|
|
|
2748 *
|
|
|
2749 * \since This function is available since SDL 3.2.0.
|
|
|
2750 */
|
|
|
2751 extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore);
|
|
|
2752
|
|
|
2753 /**
|
|
|
2754 * Toggle VSync of the given renderer.
|
|
|
2755 *
|
|
|
2756 * When a renderer is created, vsync defaults to SDL_RENDERER_VSYNC_DISABLED.
|
|
|
2757 *
|
|
|
2758 * The `vsync` parameter can be 1 to synchronize present with every vertical
|
|
|
2759 * refresh, 2 to synchronize present with every second vertical refresh, etc.,
|
|
|
2760 * SDL_RENDERER_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), or
|
|
|
2761 * SDL_RENDERER_VSYNC_DISABLED to disable. Not every value is supported by
|
|
|
2762 * every driver, so you should check the return value to see whether the
|
|
|
2763 * requested setting is supported.
|
|
|
2764 *
|
|
|
2765 * \param renderer the renderer to toggle.
|
|
|
2766 * \param vsync the vertical refresh sync interval.
|
|
|
2767 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2768 * information.
|
|
|
2769 *
|
|
|
2770 * \threadsafety This function should only be called on the main thread.
|
|
|
2771 *
|
|
|
2772 * \since This function is available since SDL 3.2.0.
|
|
|
2773 *
|
|
|
2774 * \sa SDL_GetRenderVSync
|
|
|
2775 */
|
|
|
2776 extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync);
|
|
|
2777
|
|
|
2778 #define SDL_RENDERER_VSYNC_DISABLED 0
|
|
|
2779 #define SDL_RENDERER_VSYNC_ADAPTIVE (-1)
|
|
|
2780
|
|
|
2781 /**
|
|
|
2782 * Get VSync of the given renderer.
|
|
|
2783 *
|
|
|
2784 * \param renderer the renderer to toggle.
|
|
|
2785 * \param vsync an int filled with the current vertical refresh sync interval.
|
|
|
2786 * See SDL_SetRenderVSync() for the meaning of the value.
|
|
|
2787 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2788 * information.
|
|
|
2789 *
|
|
|
2790 * \threadsafety This function should only be called on the main thread.
|
|
|
2791 *
|
|
|
2792 * \since This function is available since SDL 3.2.0.
|
|
|
2793 *
|
|
|
2794 * \sa SDL_SetRenderVSync
|
|
|
2795 */
|
|
|
2796 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync);
|
|
|
2797
|
|
|
2798 /**
|
|
|
2799 * The size, in pixels, of a single SDL_RenderDebugText() character.
|
|
|
2800 *
|
|
|
2801 * The font is monospaced and square, so this applies to all characters.
|
|
|
2802 *
|
|
|
2803 * \since This macro is available since SDL 3.2.0.
|
|
|
2804 *
|
|
|
2805 * \sa SDL_RenderDebugText
|
|
|
2806 */
|
|
|
2807 #define SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8
|
|
|
2808
|
|
|
2809 /**
|
|
|
2810 * Draw debug text to an SDL_Renderer.
|
|
|
2811 *
|
|
|
2812 * This function will render a string of text to an SDL_Renderer. Note that
|
|
|
2813 * this is a convenience function for debugging, with severe limitations, and
|
|
|
2814 * not intended to be used for production apps and games.
|
|
|
2815 *
|
|
|
2816 * Among these limitations:
|
|
|
2817 *
|
|
|
2818 * - It accepts UTF-8 strings, but will only renders ASCII characters.
|
|
|
2819 * - It has a single, tiny size (8x8 pixels). You can use logical presentation
|
|
|
2820 * or SDL_SetRenderScale() to adjust it.
|
|
|
2821 * - It uses a simple, hardcoded bitmap font. It does not allow different font
|
|
|
2822 * selections and it does not support truetype, for proper scaling.
|
|
|
2823 * - It does no word-wrapping and does not treat newline characters as a line
|
|
|
2824 * break. If the text goes out of the window, it's gone.
|
|
|
2825 *
|
|
|
2826 * For serious text rendering, there are several good options, such as
|
|
|
2827 * SDL_ttf, stb_truetype, or other external libraries.
|
|
|
2828 *
|
|
|
2829 * On first use, this will create an internal texture for rendering glyphs.
|
|
|
2830 * This texture will live until the renderer is destroyed.
|
|
|
2831 *
|
|
|
2832 * The text is drawn in the color specified by SDL_SetRenderDrawColor().
|
|
|
2833 *
|
|
|
2834 * \param renderer the renderer which should draw a line of text.
|
|
|
2835 * \param x the x coordinate where the top-left corner of the text will draw.
|
|
|
2836 * \param y the y coordinate where the top-left corner of the text will draw.
|
|
|
2837 * \param str the string to render.
|
|
|
2838 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2839 * information.
|
|
|
2840 *
|
|
|
2841 * \threadsafety This function should only be called on the main thread.
|
|
|
2842 *
|
|
|
2843 * \since This function is available since SDL 3.2.0.
|
|
|
2844 *
|
|
|
2845 * \sa SDL_RenderDebugTextFormat
|
|
|
2846 * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE
|
|
|
2847 */
|
|
|
2848 extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugText(SDL_Renderer *renderer, float x, float y, const char *str);
|
|
|
2849
|
|
|
2850 /**
|
|
|
2851 * Draw debug text to an SDL_Renderer.
|
|
|
2852 *
|
|
|
2853 * This function will render a printf()-style format string to a renderer.
|
|
|
2854 * Note that this is a convenience function for debugging, with severe
|
|
|
2855 * limitations, and is not intended to be used for production apps and games.
|
|
|
2856 *
|
|
|
2857 * For the full list of limitations and other useful information, see
|
|
|
2858 * SDL_RenderDebugText.
|
|
|
2859 *
|
|
|
2860 * \param renderer the renderer which should draw the text.
|
|
|
2861 * \param x the x coordinate where the top-left corner of the text will draw.
|
|
|
2862 * \param y the y coordinate where the top-left corner of the text will draw.
|
|
|
2863 * \param fmt the format string to draw.
|
|
|
2864 * \param ... additional parameters matching % tokens in the `fmt` string, if
|
|
|
2865 * any.
|
|
|
2866 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2867 * information.
|
|
|
2868 *
|
|
|
2869 * \threadsafety This function should only be called on the main thread.
|
|
|
2870 *
|
|
|
2871 * \since This function is available since SDL 3.2.0.
|
|
|
2872 *
|
|
|
2873 * \sa SDL_RenderDebugText
|
|
|
2874 * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE
|
|
|
2875 */
|
|
|
2876 extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugTextFormat(SDL_Renderer *renderer, float x, float y, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(4);
|
|
|
2877
|
|
|
2878 /**
|
|
|
2879 * Set default scale mode for new textures for given renderer.
|
|
|
2880 *
|
|
|
2881 * When a renderer is created, scale_mode defaults to SDL_SCALEMODE_LINEAR.
|
|
|
2882 *
|
|
|
2883 * \param renderer the renderer to update.
|
|
|
2884 * \param scale_mode the scale mode to change to for new textures.
|
|
|
2885 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2886 * information.
|
|
|
2887 *
|
|
|
2888 * \threadsafety This function should only be called on the main thread.
|
|
|
2889 *
|
|
|
2890 * \since This function is available since SDL 3.4.0.
|
|
|
2891 *
|
|
|
2892 * \sa SDL_GetDefaultTextureScaleMode
|
|
|
2893 */
|
|
|
2894 extern SDL_DECLSPEC bool SDLCALL SDL_SetDefaultTextureScaleMode(SDL_Renderer *renderer, SDL_ScaleMode scale_mode);
|
|
|
2895
|
|
|
2896 /**
|
|
|
2897 * Get default texture scale mode of the given renderer.
|
|
|
2898 *
|
|
|
2899 * \param renderer the renderer to get data from.
|
|
|
2900 * \param scale_mode a SDL_ScaleMode filled with current default scale mode.
|
|
|
2901 * See SDL_SetDefaultTextureScaleMode() for the meaning of
|
|
|
2902 * the value.
|
|
|
2903 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2904 * information.
|
|
|
2905 *
|
|
|
2906 * \threadsafety This function should only be called on the main thread.
|
|
|
2907 *
|
|
|
2908 * \since This function is available since SDL 3.4.0.
|
|
|
2909 *
|
|
|
2910 * \sa SDL_SetDefaultTextureScaleMode
|
|
|
2911 */
|
|
|
2912 extern SDL_DECLSPEC bool SDLCALL SDL_GetDefaultTextureScaleMode(SDL_Renderer *renderer, SDL_ScaleMode *scale_mode);
|
|
|
2913
|
|
|
2914 /**
|
|
|
2915 * A structure specifying the parameters of a GPU render state.
|
|
|
2916 *
|
|
|
2917 * \since This struct is available since SDL 3.4.0.
|
|
|
2918 *
|
|
|
2919 * \sa SDL_CreateGPURenderState
|
|
|
2920 */
|
|
|
2921 typedef struct SDL_GPURenderStateCreateInfo
|
|
|
2922 {
|
|
|
2923 SDL_GPUShader *fragment_shader; /**< The fragment shader to use when this render state is active */
|
|
|
2924
|
|
|
2925 Sint32 num_sampler_bindings; /**< The number of additional fragment samplers to bind when this render state is active */
|
|
|
2926 const SDL_GPUTextureSamplerBinding *sampler_bindings; /**< Additional fragment samplers to bind when this render state is active */
|
|
|
2927
|
|
|
2928 Sint32 num_storage_textures; /**< The number of storage textures to bind when this render state is active */
|
|
|
2929 SDL_GPUTexture *const *storage_textures; /**< Storage textures to bind when this render state is active */
|
|
|
2930
|
|
|
2931 Sint32 num_storage_buffers; /**< The number of storage buffers to bind when this render state is active */
|
|
|
2932 SDL_GPUBuffer *const *storage_buffers; /**< Storage buffers to bind when this render state is active */
|
|
|
2933
|
|
|
2934 SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
|
|
|
2935 } SDL_GPURenderStateCreateInfo;
|
|
|
2936
|
|
|
2937 /**
|
|
|
2938 * A custom GPU render state.
|
|
|
2939 *
|
|
|
2940 * \since This struct is available since SDL 3.4.0.
|
|
|
2941 *
|
|
|
2942 * \sa SDL_CreateGPURenderState
|
|
|
2943 * \sa SDL_SetGPURenderStateFragmentUniforms
|
|
|
2944 * \sa SDL_SetGPURenderState
|
|
|
2945 * \sa SDL_DestroyGPURenderState
|
|
|
2946 */
|
|
|
2947 typedef struct SDL_GPURenderState SDL_GPURenderState;
|
|
|
2948
|
|
|
2949 /**
|
|
|
2950 * Create custom GPU render state.
|
|
|
2951 *
|
|
|
2952 * \param renderer the renderer to use.
|
|
|
2953 * \param createinfo a struct describing the GPU render state to create.
|
|
|
2954 * \returns a custom GPU render state or NULL on failure; call SDL_GetError()
|
|
|
2955 * for more information.
|
|
|
2956 *
|
|
|
2957 * \threadsafety This function should be called on the thread that created the
|
|
|
2958 * renderer.
|
|
|
2959 *
|
|
|
2960 * \since This function is available since SDL 3.4.0.
|
|
|
2961 *
|
|
|
2962 * \sa SDL_SetGPURenderStateFragmentUniforms
|
|
|
2963 * \sa SDL_SetGPURenderState
|
|
|
2964 * \sa SDL_DestroyGPURenderState
|
|
|
2965 */
|
|
|
2966 extern SDL_DECLSPEC SDL_GPURenderState * SDLCALL SDL_CreateGPURenderState(SDL_Renderer *renderer, SDL_GPURenderStateCreateInfo *createinfo);
|
|
|
2967
|
|
|
2968 /**
|
|
|
2969 * Set fragment shader uniform variables in a custom GPU render state.
|
|
|
2970 *
|
|
|
2971 * The data is copied and will be pushed using
|
|
|
2972 * SDL_PushGPUFragmentUniformData() during draw call execution.
|
|
|
2973 *
|
|
|
2974 * \param state the state to modify.
|
|
|
2975 * \param slot_index the fragment uniform slot to push data to.
|
|
|
2976 * \param data client data to write.
|
|
|
2977 * \param length the length of the data to write.
|
|
|
2978 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2979 * information.
|
|
|
2980 *
|
|
|
2981 * \threadsafety This function should be called on the thread that created the
|
|
|
2982 * renderer.
|
|
|
2983 *
|
|
|
2984 * \since This function is available since SDL 3.4.0.
|
|
|
2985 */
|
|
|
2986 extern SDL_DECLSPEC bool SDLCALL SDL_SetGPURenderStateFragmentUniforms(SDL_GPURenderState *state, Uint32 slot_index, const void *data, Uint32 length);
|
|
|
2987
|
|
|
2988 /**
|
|
|
2989 * Set custom GPU render state.
|
|
|
2990 *
|
|
|
2991 * This function sets custom GPU render state for subsequent draw calls. This
|
|
|
2992 * allows using custom shaders with the GPU renderer.
|
|
|
2993 *
|
|
|
2994 * \param renderer the renderer to use.
|
|
|
2995 * \param state the state to to use, or NULL to clear custom GPU render state.
|
|
|
2996 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2997 * information.
|
|
|
2998 *
|
|
|
2999 * \threadsafety This function should be called on the thread that created the
|
|
|
3000 * renderer.
|
|
|
3001 *
|
|
|
3002 * \since This function is available since SDL 3.4.0.
|
|
|
3003 */
|
|
|
3004 extern SDL_DECLSPEC bool SDLCALL SDL_SetGPURenderState(SDL_Renderer *renderer, SDL_GPURenderState *state);
|
|
|
3005
|
|
|
3006 /**
|
|
|
3007 * Destroy custom GPU render state.
|
|
|
3008 *
|
|
|
3009 * \param state the state to destroy.
|
|
|
3010 *
|
|
|
3011 * \threadsafety This function should be called on the thread that created the
|
|
|
3012 * renderer.
|
|
|
3013 *
|
|
|
3014 * \since This function is available since SDL 3.4.0.
|
|
|
3015 *
|
|
|
3016 * \sa SDL_CreateGPURenderState
|
|
|
3017 */
|
|
|
3018 extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPURenderState(SDL_GPURenderState *state);
|
|
|
3019
|
|
|
3020 /* Ends C function definitions when using C++ */
|
|
|
3021 #ifdef __cplusplus
|
|
|
3022 }
|
|
|
3023 #endif
|
|
|
3024 #include <SDL3/SDL_close_code.h>
|
|
|
3025
|
|
|
3026 #endif /* SDL_render_h_ */
|
