This repository has been archived by the owner on Feb 11, 2021. It is now read-only.
/
SDL_video.h
1370 lines (1235 loc) · 46.6 KB
1
2
/*
SDL - Simple DirectMedia Layer
3
Copyright (C) 1997-2010 Sam Lantinga
4
5
This library is free software; you can redistribute it and/or
6
modify it under the terms of the GNU Lesser General Public
7
License as published by the Free Software Foundation; either
8
version 2.1 of the License, or (at your option) any later version.
9
10
11
12
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13
Lesser General Public License for more details.
14
15
16
17
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18
19
Sam Lantinga
20
slouken@libsdl.org
21
22
*/
23
/**
24
25
26
* \file SDL_video.h
*
* Header file for SDL video functions.
27
*/
28
29
30
31
#ifndef _SDL_video_h
#define _SDL_video_h
32
#include "SDL_stdinc.h"
33
#include "SDL_pixels.h"
34
#include "SDL_rect.h"
35
#include "SDL_blendmode.h"
36
#include "SDL_surface.h"
37
38
39
40
#include "begin_code.h"
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
41
/* *INDENT-OFF* */
42
extern "C" {
43
/* *INDENT-ON* */
44
45
#endif
46
/**
47
48
49
50
51
52
53
* \brief The structure that defines a display mode
*
* \sa SDL_GetNumDisplayModes()
* \sa SDL_GetDisplayMode()
* \sa SDL_GetDesktopDisplayMode()
* \sa SDL_GetCurrentDisplayMode()
* \sa SDL_GetClosestDisplayMode()
54
55
* \sa SDL_SetWindowDisplayMode()
* \sa SDL_GetWindowDisplayMode()
56
57
58
59
60
61
62
63
64
65
66
*/
typedef struct
{
Uint32 format; /**< pixel format */
int w; /**< width */
int h; /**< height */
int refresh_rate; /**< refresh rate (or zero for unspecified) */
void *driverdata; /**< driver-specific data, initialize to 0 */
} SDL_DisplayMode;
/**
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
* \brief The type used to identify a window
*
* \sa SDL_CreateWindow()
* \sa SDL_CreateWindowFrom()
* \sa SDL_DestroyWindow()
* \sa SDL_GetWindowData()
* \sa SDL_GetWindowFlags()
* \sa SDL_GetWindowGrab()
* \sa SDL_GetWindowPosition()
* \sa SDL_GetWindowSize()
* \sa SDL_GetWindowTitle()
* \sa SDL_HideWindow()
* \sa SDL_MaximizeWindow()
* \sa SDL_MinimizeWindow()
* \sa SDL_RaiseWindow()
* \sa SDL_RestoreWindow()
* \sa SDL_SetWindowData()
* \sa SDL_SetWindowFullscreen()
* \sa SDL_SetWindowGrab()
* \sa SDL_SetWindowIcon()
* \sa SDL_SetWindowPosition()
* \sa SDL_SetWindowSize()
* \sa SDL_SetWindowTitle()
* \sa SDL_ShowWindow()
91
*/
92
typedef struct SDL_Window SDL_Window;
93
94
/**
95
96
97
* \brief The flags on a window
*
* \sa SDL_GetWindowFlags()
98
99
100
101
102
103
104
105
*/
typedef enum
{
SDL_WINDOW_FULLSCREEN = 0x00000001, /**< fullscreen window, implies borderless */
SDL_WINDOW_OPENGL = 0x00000002, /**< window usable with OpenGL context */
SDL_WINDOW_SHOWN = 0x00000004, /**< window is visible */
SDL_WINDOW_BORDERLESS = 0x00000008, /**< no window decoration */
SDL_WINDOW_RESIZABLE = 0x00000010, /**< window can be resized */
106
107
SDL_WINDOW_MINIMIZED = 0x00000020, /**< window is minimized */
SDL_WINDOW_MAXIMIZED = 0x00000040, /**< window is maximized */
108
109
SDL_WINDOW_INPUT_GRABBED = 0x00000100, /**< window has grabbed input focus */
SDL_WINDOW_INPUT_FOCUS = 0x00000200, /**< window has input focus */
110
111
SDL_WINDOW_MOUSE_FOCUS = 0x00000400, /**< window has mouse focus */
SDL_WINDOW_FOREIGN = 0x00000800 /**< window not created by SDL */
112
113
114
} SDL_WindowFlags;
/**
115
* \brief Used to indicate that you don't care what the window position is.
116
117
*/
#define SDL_WINDOWPOS_UNDEFINED 0x7FFFFFF
118
119
/**
120
* \brief Used to indicate that the window position should be centered.
121
122
123
124
*/
#define SDL_WINDOWPOS_CENTERED 0x7FFFFFE
/**
125
* \brief Event subtype for window events
126
127
128
*/
typedef enum
{
129
130
131
132
133
134
135
136
137
138
139
140
SDL_WINDOWEVENT_NONE, /**< Never used */
SDL_WINDOWEVENT_SHOWN, /**< Window has been shown */
SDL_WINDOWEVENT_HIDDEN, /**< Window has been hidden */
SDL_WINDOWEVENT_EXPOSED, /**< Window has been exposed and should be
redrawn */
SDL_WINDOWEVENT_MOVED, /**< Window has been moved to data1, data2
*/
SDL_WINDOWEVENT_RESIZED, /**< Window size changed to data1xdata2 */
SDL_WINDOWEVENT_MINIMIZED, /**< Window has been minimized */
SDL_WINDOWEVENT_MAXIMIZED, /**< Window has been maximized */
SDL_WINDOWEVENT_RESTORED, /**< Window has been restored to normal size
and position */
141
142
143
144
SDL_WINDOWEVENT_ENTER, /**< Window has gained mouse focus */
SDL_WINDOWEVENT_LEAVE, /**< Window has lost mouse focus */
SDL_WINDOWEVENT_FOCUS_GAINED, /**< Window has gained keyboard focus */
SDL_WINDOWEVENT_FOCUS_LOST, /**< Window has lost keyboard focus */
145
146
SDL_WINDOWEVENT_CLOSE /**< The window manager requests that the
window be closed */
147
148
149
} SDL_WindowEventID;
/**
150
* \brief Flags used when creating a rendering context
151
152
153
*/
typedef enum
{
154
155
156
157
158
SDL_RENDERER_PRESENTVSYNC = 0x00000020, /**< Present is synchronized
with the refresh rate */
SDL_RENDERER_ACCELERATED = 0x00000040 /**< The renderer uses hardware
acceleration */
159
} SDL_RendererFlags;
160
161
162
/**
* \brief Information on the capabilities of a render driver or context.
163
164
165
166
*/
typedef struct SDL_RendererInfo
{
const char *name; /**< The name of the renderer */
167
Uint32 flags; /**< Supported ::SDL_RendererFlags */
168
Uint32 num_texture_formats; /**< The number of available texture formats */
169
Uint32 texture_formats[50]; /**< The available texture formats */
170
171
172
173
174
int max_texture_width; /**< The maximimum texture width */
int max_texture_height; /**< The maximimum texture height */
} SDL_RendererInfo;
/**
175
* \brief The access pattern allowed for a texture.
176
177
178
*/
typedef enum
{
179
180
SDL_TEXTUREACCESS_STATIC, /**< Changes rarely, not lockable */
SDL_TEXTUREACCESS_STREAMING /**< Changes frequently, lockable */
181
182
} SDL_TextureAccess;
183
/**
184
* \brief The texture channel modulation used in SDL_RenderCopy().
185
186
187
188
189
*/
typedef enum
{
SDL_TEXTUREMODULATE_NONE = 0x00000000, /**< No modulation */
SDL_TEXTUREMODULATE_COLOR = 0x00000001, /**< srcC = srcC * color */
190
SDL_TEXTUREMODULATE_ALPHA = 0x00000002 /**< srcA = srcA * alpha */
191
192
} SDL_TextureModulate;
193
/**
194
* \brief An efficient driver-specific representation of pixel data
195
*/
196
197
struct SDL_Texture;
typedef struct SDL_Texture SDL_Texture;
198
199
/**
200
* \brief An opaque handle to an OpenGL context.
201
202
203
204
*/
typedef void *SDL_GLContext;
/**
205
* \brief OpenGL configuration attributes
206
207
208
*/
typedef enum
{
209
210
211
212
213
214
215
216
217
218
219
SDL_GL_RED_SIZE,
SDL_GL_GREEN_SIZE,
SDL_GL_BLUE_SIZE,
SDL_GL_ALPHA_SIZE,
SDL_GL_BUFFER_SIZE,
SDL_GL_DOUBLEBUFFER,
SDL_GL_DEPTH_SIZE,
SDL_GL_STENCIL_SIZE,
SDL_GL_ACCUM_RED_SIZE,
SDL_GL_ACCUM_GREEN_SIZE,
SDL_GL_ACCUM_BLUE_SIZE,
220
SDL_GL_ACCUM_ALPHA_SIZE,
221
SDL_GL_STEREO,
222
SDL_GL_MULTISAMPLEBUFFERS,
223
SDL_GL_MULTISAMPLESAMPLES,
224
SDL_GL_ACCELERATED_VISUAL,
225
SDL_GL_RETAINED_BACKING,
226
227
SDL_GL_CONTEXT_MAJOR_VERSION,
SDL_GL_CONTEXT_MINOR_VERSION
228
229
230
231
232
} SDL_GLattr;
/* Function prototypes */
233
/**
234
235
236
* \brief Get the number of video drivers compiled into SDL
*
* \sa SDL_GetVideoDriver()
237
238
239
240
*/
extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
/**
241
242
243
244
245
246
* \brief Get the name of a built in video driver.
*
* \note The video drivers are presented in the order in which they are
* normally checked during initialization.
*
* \sa SDL_GetNumVideoDrivers()
247
248
249
250
*/
extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
/**
251
252
253
254
255
256
257
258
259
260
261
262
* \brief Initialize the video subsystem, optionally specifying a video driver.
*
* \param driver_name Initialize a specific driver by name, or NULL for the
* default video driver.
*
* \return 0 on success, -1 on error
*
* This function initializes the video subsystem; setting up a connection
* to the window manager, etc, and determines the available display modes
* and pixel formats, but does not initialize a window or graphics mode.
*
* \sa SDL_VideoQuit()
263
*/
264
extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name);
265
266
/**
267
268
269
270
271
* \brief Shuts down the video subsystem.
*
* This function closes all windows, and restores the original video mode.
*
* \sa SDL_VideoInit()
272
*/
273
extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
274
275
/**
276
277
278
279
280
281
282
* \brief Returns the name of the currently initialized video driver.
*
* \return The name of the current video driver or NULL if no driver
* has been initialized
*
* \sa SDL_GetNumVideoDrivers()
* \sa SDL_GetVideoDriver()
283
*/
284
extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
285
286
/**
287
288
* \brief Returns the number of available video displays.
*
289
* \sa SDL_GetDisplayBounds()
290
* \sa SDL_SelectVideoDisplay()
291
*/
292
extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
293
294
295
296
297
298
299
300
301
302
303
/**
* \brief Get the desktop area represented by a display, with the primary
* display located at 0,0
*
* \return 0 on success, or -1 if the index is out of range.
*
* \sa SDL_GetNumVideoDisplays()
*/
extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int index, SDL_Rect * rect);
304
/**
305
306
307
308
309
310
* \brief Set the index of the currently selected display.
*
* \return 0 on success, or -1 if the index is out of range.
*
* \sa SDL_GetNumVideoDisplays()
* \sa SDL_GetCurrentVideoDisplay()
311
*/
312
extern DECLSPEC int SDLCALL SDL_SelectVideoDisplay(int index);
313
314
/**
315
316
317
318
319
320
* \brief Get the index of the currently selected display.
*
* \return The index of the currently selected display.
*
* \sa SDL_GetNumVideoDisplays()
* \sa SDL_SelectVideoDisplay()
321
322
323
*/
extern DECLSPEC int SDLCALL SDL_GetCurrentVideoDisplay(void);
324
/**
325
326
327
* \brief Returns the number of available display modes for the current display.
*
* \sa SDL_GetDisplayMode()
328
*/
329
extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(void);
330
331
/**
332
333
334
335
336
337
338
339
340
* \brief Fill in information about a specific display mode.
*
* \note The display modes are sorted in this priority:
* \li bits per pixel -> more colors to fewer colors
* \li width -> largest to smallest
* \li height -> largest to smallest
* \li refresh rate -> highest to lowest
*
* \sa SDL_GetNumDisplayModes()
341
*/
342
343
extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int index,
SDL_DisplayMode * mode);
344
345
/**
346
347
* \brief Fill in information about the desktop display mode for the current
* display.
348
*/
349
extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(SDL_DisplayMode * mode);
350
351
/**
352
* \brief Fill in information about the current display mode.
353
*/
354
extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(SDL_DisplayMode * mode);
355
356
357
/**
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
* \brief Get the closest match to the requested display mode.
*
* \param mode The desired display mode
* \param closest A pointer to a display mode to be filled in with the closest
* match of the available display modes.
*
* \return The passed in value \c closest, or NULL if no matching video mode
* was available.
*
* The available display modes are scanned, and \c closest is filled in with the
* closest mode matching the requested mode and returned. The mode format and
* refresh_rate default to the desktop mode if they are 0. The modes are
* scanned with size being first priority, format being second priority, and
* finally checking the refresh_rate. If all the available modes are too
* small, then NULL is returned.
*
* \sa SDL_GetNumDisplayModes()
* \sa SDL_GetDisplayMode()
376
*/
377
378
379
380
381
382
383
extern DECLSPEC SDL_DisplayMode *SDLCALL SDL_GetClosestDisplayMode(const
SDL_DisplayMode
* mode,
SDL_DisplayMode
* closest);
/**
384
* \brief Set the display mode used when a fullscreen window is visible
385
386
* on the currently selected display. By default the window's
* dimensions and the desktop format and refresh rate are used.
387
*
388
* \param mode The mode to use, or NULL for the default mode.
389
390
391
*
* \return 0 on success, or -1 if setting the display mode failed.
*
392
* \sa SDL_GetWindowDisplayMode()
393
* \sa SDL_SetWindowFullscreen()
394
*/
395
extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window,
396
const SDL_DisplayMode
397
* mode);
398
399
/**
400
401
* \brief Fill in information about the display mode used when a fullscreen
* window is visible on the currently selected display.
402
403
404
*
* \sa SDL_SetWindowDisplayMode()
* \sa SDL_SetWindowFullscreen()
405
*/
406
extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window,
407
SDL_DisplayMode * mode);
408
409
/**
410
411
412
413
* \brief Set the palette entries for indexed display modes.
*
* \return 0 on success, or -1 if the display mode isn't palettized or the
* colors couldn't be set.
414
415
416
417
418
419
*/
extern DECLSPEC int SDLCALL SDL_SetDisplayPalette(const SDL_Color * colors,
int firstcolor,
int ncolors);
/**
420
421
422
* \brief Gets the palette entries for indexed display modes.
*
* \return 0 on success, or -1 if the display mode isn't palettized
423
424
425
426
427
428
*/
extern DECLSPEC int SDLCALL SDL_GetDisplayPalette(SDL_Color * colors,
int firstcolor,
int ncolors);
/**
429
430
431
432
433
434
* \brief Set the gamma correction for each of the color channels on the
* currently selected display.
*
* \return 0 on success, or -1 if setting the gamma isn't supported.
*
* \sa SDL_SetGammaRamp()
435
*/
436
extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
437
438
/**
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
* \brief Set the gamma ramp for the currently selected display.
*
* \param red The translation table for the red channel, or NULL.
* \param green The translation table for the green channel, or NULL.
* \param blue The translation table for the blue channel, or NULL.
*
* \return 0 on success, or -1 if gamma ramps are unsupported.
*
* Set the gamma translation table for the red, green, and blue channels
* of the video hardware. Each table is an array of 256 16-bit quantities,
* representing a mapping between the input and output for that channel.
* The input is the index into the array, and the output is the 16-bit
* gamma value at that index, scaled to the output color precision.
*
* \sa SDL_GetGammaRamp()
454
*/
455
456
457
extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 * red,
const Uint16 * green,
const Uint16 * blue);
458
459
/**
460
461
462
463
464
465
466
467
468
469
470
471
* \brief Get the gamma ramp for the currently selected display.
*
* \param red A pointer to a 256 element array of 16-bit quantities to hold
* the translation table for the red channel, or NULL.
* \param green A pointer to a 256 element array of 16-bit quantities to hold
* the translation table for the green channel, or NULL.
* \param blue A pointer to a 256 element array of 16-bit quantities to hold
* the translation table for the blue channel, or NULL.
*
* \return 0 on success, or -1 if gamma ramps are unsupported.
*
* \sa SDL_SetGammaRamp()
472
*/
473
474
extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 * red, Uint16 * green,
Uint16 * blue);
475
476
477
/**
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
* \brief Create a window with the specified position, dimensions, and flags.
*
* \param title The title of the window, in UTF-8 encoding.
* \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
* ::SDL_WINDOWPOS_UNDEFINED.
* \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
* ::SDL_WINDOWPOS_UNDEFINED.
* \param w The width of the window.
* \param h The height of the window.
* \param flags The flags for the window, a mask of any of the following:
* ::SDL_WINDOW_FULLSCREEN, ::SDL_WINDOW_OPENGL,
* ::SDL_WINDOW_SHOWN, ::SDL_WINDOW_BORDERLESS,
* ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
* ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_INPUT_GRABBED.
*
* \return The id of the window created, or zero if window creation failed.
*
* \sa SDL_DestroyWindow()
496
*/
497
extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title,
498
499
500
501
int x, int y, int w,
int h, Uint32 flags);
/**
502
* \brief Create an SDL window from an existing native window.
503
504
505
506
507
508
*
* \param data A pointer to driver-dependent window creation data
*
* \return The id of the window created, or zero if window creation failed.
*
* \sa SDL_DestroyWindow()
509
*/
510
511
512
extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data);
/**
513
* \brief Get the numeric ID of a window, for logging purposes.
514
515
516
517
518
519
520
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window);
/**
* \brief Get a window from a stored ID, or NULL if it doesn't exist.
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id);
521
522
/**
523
* \brief Get the window flags.
524
*/
525
extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window);
526
527
/**
528
* \brief Set the title of a window, in UTF-8 format.
529
530
*
* \sa SDL_GetWindowTitle()
531
*/
532
extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window,
533
534
535
const char *title);
/**
536
* \brief Get the title of a window, in UTF-8 format.
537
538
*
* \sa SDL_SetWindowTitle()
539
*/
540
extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window);
541
542
/**
543
* \brief Set the icon for a window.
544
*
545
* \param icon The icon for the window.
546
*/
547
extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window,
548
SDL_Surface * icon);
549
550
/**
551
* \brief Associate an arbitrary pointer with a window.
552
553
*
* \sa SDL_GetWindowData()
554
*/
555
extern DECLSPEC void SDLCALL SDL_SetWindowData(SDL_Window * window,
556
557
558
void *userdata);
/**
559
* \brief Retrieve the data pointer associated with a window.
560
561
*
* \sa SDL_SetWindowData()
562
*/
563
extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window);
564
565
/**
566
* \brief Set the position of a window.
567
*
568
* \param window The window to reposition.
569
570
571
572
573
574
575
576
* \param x The x coordinate of the window, ::SDL_WINDOWPOS_CENTERED, or
::SDL_WINDOWPOS_UNDEFINED.
* \param y The y coordinate of the window, ::SDL_WINDOWPOS_CENTERED, or
::SDL_WINDOWPOS_UNDEFINED.
*
* \note The window coordinate origin is the upper left of the display.
*
* \sa SDL_GetWindowPosition()
577
*/
578
extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window,
579
580
581
int x, int y);
/**
582
* \brief Get the position of a window.
583
584
*
* \sa SDL_SetWindowPosition()
585
*/
586
extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window,
587
588
589
int *x, int *y);
/**
590
* \brief Set the size of a window's client area.
591
592
593
594
595
*
* \note You can't change the size of a fullscreen window, it automatically
* matches the size of the display mode.
*
* \sa SDL_GetWindowSize()
596
*/
597
extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w,
598
599
600
int h);
/**
601
* \brief Get the size of a window's client area.
602
603
*
* \sa SDL_SetWindowSize()
604
*/
605
extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w,
606
607
608
int *h);
/**
609
* \brief Show a window.
610
611
*
* \sa SDL_HideWindow()
612
*/
613
extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window);
614
615
/**
616
* \brief Hide a window.
617
618
*
* \sa SDL_ShowWindow()
619
*/
620
extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window);
621
622
/**
623
* \brief Raise a window above other windows and set the input focus.
624
*/
625
extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window);
626
627
/**
628
* \brief Make a window as large as possible.
629
630
*
* \sa SDL_RestoreWindow()
631
*/
632
extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window);
633
634
/**
635
* \brief Minimize a window to an iconic representation.
636
637
*
* \sa SDL_RestoreWindow()
638
*/
639
extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
640
641
/**
642
643
644
645
* \brief Restore the size and position of a minimized or maximized window.
*
* \sa SDL_MaximizeWindow()
* \sa SDL_MinimizeWindow()
646
*/
647
extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window);
648
649
/**
650
* \brief Set a window's fullscreen state.
651
652
653
*
* \return 0 on success, or -1 if setting the display mode failed.
*
654
655
* \sa SDL_SetWindowDisplayMode()
* \sa SDL_GetWindowDisplayMode()
656
*/
657
extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window,
658
659
660
int fullscreen);
/**
661
* \brief Set a window's input grab mode.
662
663
664
665
*
* \param mode This is 1 to grab input, and 0 to release input.
*
* \sa SDL_GetWindowGrab()
666
*/
667
extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
668
669
670
int mode);
/**
671
* \brief Get a window's input grab mode.
672
673
674
675
*
* \return This returns 1 if input is grabbed, and 0 otherwise.
*
* \sa SDL_SetWindowGrab()
676
*/
677
extern DECLSPEC int SDLCALL SDL_GetWindowGrab(SDL_Window * window);
678
679
/**
680
681
682
* \brief Get driver specific information about a window.
*
* \note Include SDL_syswm.h for the declaration of SDL_SysWMinfo.
683
684
*/
struct SDL_SysWMinfo;
685
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_Window * window,
686
687
688
689
struct SDL_SysWMinfo
*info);
/**
690
* \brief Destroy a window.
691
*/
692
extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window * window);
693
694
/**
695
696
697
698
699
700
701
702
703
* \brief Get the number of 2D rendering drivers available for the current
* display.
*
* A render driver is a set of code that handles rendering and texture
* management on a particular display. Normally there is only one, but
* some drivers may have several available with different capabilities.
*
* \sa SDL_GetRenderDriverInfo()
* \sa SDL_CreateRenderer()
704
*/
705
extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
706
707
/**
708
709
710
711
712
713
714
715
716
717
* \brief Get information about a specific 2D rendering driver for the current
* display.
*
* \param index The index of the driver to query information about.
* \param info A pointer to an SDL_RendererInfo struct to be filled with
* information on the rendering driver.
*
* \return 0 on success, -1 if the index was out of range.
*
* \sa SDL_CreateRenderer()
718
*/
719
720
extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index,
SDL_RendererInfo * info);
721
722
/**
723
724
* \brief Create and make active a 2D rendering context for a window.
*
725
* \param window The window where rendering is displayed.
726
727
728
729
730
731
732
733
734
* \param index The index of the rendering driver to initialize, or -1 to
* initialize the first one supporting the requested flags.
* \param flags ::SDL_RendererFlags.
*
* \return 0 on success, -1 if there was an error creating the renderer.
*
* \sa SDL_SelectRenderer()
* \sa SDL_GetRendererInfo()
* \sa SDL_DestroyRenderer()
735
*/
736
extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_Window * window,
737
738
739
int index, Uint32 flags);
/**
740
741
742
743
* \brief Select the rendering context for a particular window.
*
* \return 0 on success, -1 if the selected window doesn't have a
* rendering context.
744
*/
745
extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_Window * window);
746
747
/**
748
* \brief Get information about the current rendering context.
749
750
751
*/
extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_RendererInfo * info);
752
/**
753
754
755
756
757
758
759
760
761
762
763
764
765
* \brief Create a texture for the current rendering context.
*
* \param format The format of the texture.
* \param access One of the enumerated values in ::SDL_TextureAccess.
* \param w The width of the texture in pixels.
* \param h The height of the texture in pixels.
*
* \return The created texture is returned, or 0 if no rendering context was
* active, the format was unsupported, or the width or height were out
* of range.
*
* \sa SDL_QueryTexture()
* \sa SDL_DestroyTexture()
766
*/
767
extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(Uint32 format,
768
769
770
771
int access, int w,
int h);
/**
772
773
774
775
776
777
778
779
780
781
782
783
784
* \brief Create a texture from an existing surface.
*
* \param format The format of the texture, or 0 to pick an appropriate format.
* \param surface The surface containing pixel data used to fill the texture.
*
* \return The created texture is returned, or 0 if no rendering context was
* active, the format was unsupported, or the surface width or height
* were out of range.
*
* \note The surface is not modified or freed by this function.
*
* \sa SDL_QueryTexture()
* \sa SDL_DestroyTexture()
785
*/
786
extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(Uint32
787
788
789
790
791
format,
SDL_Surface
* surface);
/**
792
793
* \brief Query the attributes of a texture
*
794
* \param texture A texture to be queried.
795
796
797
798
799
800
801
802
* \param format A pointer filled in with the raw format of the texture. The
* actual format may differ, but pixel transfers will use this
* format.
* \param access A pointer filled in with the actual access to the texture.
* \param w A pointer filled in with the width of the texture in pixels.
* \param h A pointer filled in with the height of the texture in pixels.
*
* \return 0 on success, or -1 if the texture is not valid.
803
*/
804
extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture,
805
806
807
808
Uint32 * format, int *access,
int *w, int *h);
/**
809
810
811
* \brief Query the pixels of a texture, if the texture does not need to be
* locked for pixel access.
*
812
* \param texture A texture to be queried, which was created with
813
814
815
816
817
818
819
* ::SDL_TEXTUREACCESS_STREAMING.
* \param pixels A pointer filled with a pointer to the pixels for the
* texture.
* \param pitch A pointer filled in with the pitch of the pixel data.
*
* \return 0 on success, or -1 if the texture is not valid, or must be locked
* for pixel access.
820
*/
821
extern DECLSPEC int SDLCALL SDL_QueryTexturePixels(SDL_Texture * texture,
822
823
824
void **pixels, int *pitch);
/**
825
826
* \brief Set the color palette of an indexed texture.
*
827
* \param texture The texture to update.
828
829
830
831
832
833
* \param colors The array of RGB color data.
* \param firstcolor The first index to update.
* \param ncolors The number of palette entries to fill with the color data.
*
* \return 0 on success, or -1 if the texture is not valid or not an indexed
* texture.
834
*/
835
extern DECLSPEC int SDLCALL SDL_SetTexturePalette(SDL_Texture * texture,
836
837
838
839
840
const SDL_Color * colors,
int firstcolor,
int ncolors);
/**
841
842
* \brief Get the color palette from an indexed texture if it has one.
*
843
* \param texture The texture to update.
844
845
846
847
848
849
* \param colors The array to fill with RGB color data.
* \param firstcolor The first index to retrieve.
* \param ncolors The number of palette entries to retrieve.
*
* \return 0 on success, or -1 if the texture is not valid or not an indexed
* texture.
850
*/
851
extern DECLSPEC int SDLCALL SDL_GetTexturePalette(SDL_Texture * texture,
852
853
854
855
SDL_Color * colors,
int firstcolor,
int ncolors);
856
/**
857
858
* \brief Set an additional color value used in render copy operations.
*
859
* \param texture The texture to update.
860
861
862
* \param r The red color value multiplied into copy operations.
* \param g The green color value multiplied into copy operations.
* \param b The blue color value multiplied into copy operations.
863
864
865
866
867
*
* \return 0 on success, or -1 if the texture is not valid or color modulation
* is not supported.
*
* \sa SDL_GetTextureColorMod()
868
*/
869
extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture,
870
871
872
873
Uint8 r, Uint8 g, Uint8 b);
/**
874
875
* \brief Get the additional color value used in render copy operations.
*
876
* \param texture The texture to query.
877
878
879
* \param r A pointer filled in with the current red color value.
* \param g A pointer filled in with the current green color value.
* \param b A pointer filled in with the current blue color value.
880
881
882
883
*
* \return 0 on success, or -1 if the texture is not valid.
*
* \sa SDL_SetTextureColorMod()
884
*/
885
extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture,
886
887
888
889
Uint8 * r, Uint8 * g,
Uint8 * b);
/**
890
891
* \brief Set an additional alpha value used in render copy operations.
*
892
* \param texture The texture to update.
893
* \param alpha The alpha value multiplied into copy operations.
894
895
896
897
898
*
* \return 0 on success, or -1 if the texture is not valid or alpha modulation
* is not supported.
*
* \sa SDL_GetTextureAlphaMod()
899
*/
900
extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture,
901
902
903
Uint8 alpha);
/**
904
905
* \brief Get the additional alpha value used in render copy operations.
*
906
* \param texture The texture to query.
907
* \param alpha A pointer filled in with the current alpha value.
908
909
910
911
*
* \return 0 on success, or -1 if the texture is not valid.
*
* \sa SDL_SetTextureAlphaMod()
912
*/
913
extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture,
914
915
916
Uint8 * alpha);
/**
917
918
* \brief Set the blend mode used for texture copy operations.
*
919
* \param texture The texture to update.
920
921
922
923
924
925
926
927
928
* \param blendMode ::SDL_BlendMode to use for texture blending.
*
* \return 0 on success, or -1 if the texture is not valid or the blend mode is
* not supported.
*
* \note If the blend mode is not supported, the closest supported mode is
* chosen.
*
* \sa SDL_GetTextureBlendMode()
929
*/
930
extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture,
931
SDL_BlendMode blendMode);
932
933
/**
934
935
* \brief Get the blend mode used for texture copy operations.
*
936
* \param texture The texture to query.
937
938
939
940
941
* \param blendMode A pointer filled in with the current blend mode.
*
* \return 0 on success, or -1 if the texture is not valid.
*
* \sa SDL_SetTextureBlendMode()
942
*/
943
extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture,
944
SDL_BlendMode *blendMode);
945
946
/**
947
948
* \brief Update the given texture rectangle with new pixel data.
*
949
* \param texture The texture to update
950
951
952
953
954
955
956
957
* \param rect A pointer to the rectangle of pixels to update, or NULL to
* update the entire texture.
* \param pixels The raw pixel data.
* \param pitch The number of bytes between rows of pixel data.
*
* \return 0 on success, or -1 if the texture is not valid.
*
* \note This is a fairly slow function.
958
*/
959
extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture,
960
961
962
963
const SDL_Rect * rect,
const void *pixels, int pitch);
/**
964
965
* \brief Lock a portion of the texture for pixel access.
*
966
* \param texture The texture to lock for access, which was created with
967
968
969
970
971
972
973
974
975
976
977
978
979
980
* ::SDL_TEXTUREACCESS_STREAMING.
* \param rect A pointer to the rectangle to lock for access. If the rect
* is NULL, the entire texture will be locked.
* \param markDirty If this is nonzero, the locked area will be marked dirty
* when the texture is unlocked.
* \param pixels This is filled in with a pointer to the locked pixels,
* appropriately offset by the locked area.
* \param pitch This is filled in with the pitch of the locked pixels.
*
* \return 0 on success, or -1 if the texture is not valid or was created with
* ::SDL_TEXTUREACCESS_STATIC.
*
* \sa SDL_DirtyTexture()
* \sa SDL_UnlockTexture()
981
*/
982
extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture,
983
984
985
986
987
const SDL_Rect * rect,
int markDirty, void **pixels,
int *pitch);
/**
988
989
990
991
* \brief Unlock a texture, uploading the changes to video memory, if needed.
*
* \sa SDL_LockTexture()
* \sa SDL_DirtyTexture()
992
*/
993
extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture);
994
995
/**
996
997
* \brief Mark the specified rectangles of the texture as dirty.
*
998
* \param texture The texture to mark dirty, which was created with
999
1000
* ::SDL_TEXTUREACCESS_STREAMING.
* \param numrects The number of rectangles pointed to by rects.