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