]>
Commit | Line | Data |
---|---|---|
7407ac7f BB |
1 | /* |
2 | Simple DirectMedia Layer | |
3 | Copyright (C) 1997-2013 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_hints.h | |
24 | * | |
25 | * Official documentation for SDL configuration variables | |
26 | * | |
27 | * This file contains functions to set and get configuration hints, | |
28 | * as well as listing each of them alphabetically. | |
29 | * | |
30 | * The convention for naming hints is SDL_HINT_X, where "SDL_X" is | |
31 | * the environment variable that can be used to override the default. | |
32 | * | |
33 | * In general these hints are just that - they may or may not be | |
34 | * supported or applicable on any given platform, but they provide | |
35 | * a way for an application or user to give the library a hint as | |
36 | * to how they would like the library to work. | |
37 | */ | |
38 | ||
39 | #ifndef _SDL_hints_h | |
40 | #define _SDL_hints_h | |
41 | ||
42 | #include "SDL_stdinc.h" | |
43 | ||
44 | #include "begin_code.h" | |
45 | /* Set up for C function definitions, even when using C++ */ | |
46 | #ifdef __cplusplus | |
47 | extern "C" { | |
48 | #endif | |
49 | ||
50 | /** | |
51 | * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface. | |
52 | * | |
53 | * SDL can try to accelerate the SDL screen surface by using streaming | |
54 | * textures with a 3D rendering engine. This variable controls whether and | |
55 | * how this is done. | |
56 | * | |
57 | * This variable can be set to the following values: | |
58 | * "0" - Disable 3D acceleration | |
59 | * "1" - Enable 3D acceleration, using the default renderer. | |
60 | * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.) | |
61 | * | |
62 | * By default SDL tries to make a best guess for each platform whether | |
63 | * to use acceleration or not. | |
64 | */ | |
65 | #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" | |
66 | ||
67 | /** | |
68 | * \brief A variable specifying which render driver to use. | |
69 | * | |
70 | * If the application doesn't pick a specific renderer to use, this variable | |
71 | * specifies the name of the preferred renderer. If the preferred renderer | |
72 | * can't be initialized, the normal default renderer is used. | |
73 | * | |
74 | * This variable is case insensitive and can be set to the following values: | |
75 | * "direct3d" | |
76 | * "opengl" | |
77 | * "opengles2" | |
78 | * "opengles" | |
79 | * "software" | |
80 | * | |
81 | * The default varies by platform, but it's the first one in the list that | |
82 | * is available on the current platform. | |
83 | */ | |
84 | #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" | |
85 | ||
86 | /** | |
87 | * \brief A variable controlling whether the OpenGL render driver uses shaders if they are available. | |
88 | * | |
89 | * This variable can be set to the following values: | |
90 | * "0" - Disable shaders | |
91 | * "1" - Enable shaders | |
92 | * | |
93 | * By default shaders are used if OpenGL supports them. | |
94 | */ | |
95 | #define SDL_HINT_RENDER_OPENGL_SHADERS "SDL_RENDER_OPENGL_SHADERS" | |
96 | ||
97 | /** | |
98 | * \brief A variable controlling the scaling quality | |
99 | * | |
100 | * This variable can be set to the following values: | |
101 | * "0" or "nearest" - Nearest pixel sampling | |
102 | * "1" or "linear" - Linear filtering (supported by OpenGL and Direct3D) | |
103 | * "2" or "best" - Currently this is the same as "linear" | |
104 | * | |
105 | * By default nearest pixel sampling is used | |
106 | */ | |
107 | #define SDL_HINT_RENDER_SCALE_QUALITY "SDL_RENDER_SCALE_QUALITY" | |
108 | ||
109 | /** | |
110 | * \brief A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing. | |
111 | * | |
112 | * This variable can be set to the following values: | |
113 | * "0" - Disable vsync | |
114 | * "1" - Enable vsync | |
115 | * | |
116 | * By default SDL does not sync screen surface updates with vertical refresh. | |
117 | */ | |
118 | #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" | |
119 | ||
120 | /** | |
121 | * \brief A variable controlling whether the X11 VidMode extension should be used. | |
122 | * | |
123 | * This variable can be set to the following values: | |
124 | * "0" - Disable XVidMode | |
125 | * "1" - Enable XVidMode | |
126 | * | |
127 | * By default SDL will use XVidMode if it is available. | |
128 | */ | |
129 | #define SDL_HINT_VIDEO_X11_XVIDMODE "SDL_VIDEO_X11_XVIDMODE" | |
130 | ||
131 | /** | |
132 | * \brief A variable controlling whether the X11 Xinerama extension should be used. | |
133 | * | |
134 | * This variable can be set to the following values: | |
135 | * "0" - Disable Xinerama | |
136 | * "1" - Enable Xinerama | |
137 | * | |
138 | * By default SDL will use Xinerama if it is available. | |
139 | */ | |
140 | #define SDL_HINT_VIDEO_X11_XINERAMA "SDL_VIDEO_X11_XINERAMA" | |
141 | ||
142 | /** | |
143 | * \brief A variable controlling whether the X11 XRandR extension should be used. | |
144 | * | |
145 | * This variable can be set to the following values: | |
146 | * "0" - Disable XRandR | |
147 | * "1" - Enable XRandR | |
148 | * | |
149 | * By default SDL will not use XRandR because of window manager issues. | |
150 | */ | |
151 | #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" | |
152 | ||
153 | /** | |
154 | * \brief A variable controlling whether grabbing input grabs the keyboard | |
155 | * | |
156 | * This variable can be set to the following values: | |
157 | * "0" - Grab will affect only the mouse | |
158 | * "1" - Grab will affect mouse and keyboard | |
159 | * | |
160 | * By default SDL will not grab the keyboard so system shortcuts still work. | |
161 | */ | |
162 | #define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD" | |
163 | ||
164 | /** | |
165 | * \brief Minimize your SDL_Window if it loses key focus when in Fullscreen mode. Defaults to true. | |
166 | * | |
167 | */ | |
168 | #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" | |
169 | ||
170 | ||
171 | /** | |
172 | * \brief A variable controlling whether the idle timer is disabled on iOS. | |
173 | * | |
174 | * When an iOS app does not receive touches for some time, the screen is | |
175 | * dimmed automatically. For games where the accelerometer is the only input | |
176 | * this is problematic. This functionality can be disabled by setting this | |
177 | * hint. | |
178 | * | |
179 | * This variable can be set to the following values: | |
180 | * "0" - Enable idle timer | |
181 | * "1" - Disable idle timer | |
182 | */ | |
183 | #define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED" | |
184 | ||
185 | /** | |
186 | * \brief A variable controlling which orientations are allowed on iOS. | |
187 | * | |
188 | * In some circumstances it is necessary to be able to explicitly control | |
189 | * which UI orientations are allowed. | |
190 | * | |
191 | * This variable is a space delimited list of the following values: | |
192 | * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown" | |
193 | */ | |
194 | #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS" | |
195 | ||
196 | ||
197 | /** | |
198 | * \brief A variable that lets you disable the detection and use of Xinput gamepad devices | |
199 | * | |
200 | * The variable can be set to the following values: | |
201 | * "0" - Disable XInput timer (only uses direct input) | |
202 | * "1" - Enable XInput timer (the default) | |
203 | */ | |
204 | #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" | |
205 | ||
206 | ||
207 | /** | |
208 | * \brief A variable that lets you manually hint extra gamecontroller db entries | |
209 | * | |
210 | * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h | |
211 | * | |
212 | * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) | |
213 | * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() | |
214 | */ | |
215 | #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" | |
216 | ||
217 | ||
218 | /** | |
219 | * \brief A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background. | |
220 | * | |
221 | * The variable can be set to the following values: | |
222 | * "0" - Disable joystick & gamecontroller input events when the | |
223 | * application is in the background. | |
224 | * "1" - Enable joystick & gamecontroller input events when the | |
225 | * application is in the backgroumd. | |
226 | * | |
227 | * The default value is "0". This hint may be set at any time. | |
228 | */ | |
229 | #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" | |
230 | ||
231 | ||
232 | /** | |
233 | * \brief If set to 0 then never set the top most bit on a SDL Window, even if the video mode expects it. | |
234 | * This is a debugging aid for developers and not expected to be used by end users. The default is "1" | |
235 | * | |
236 | * This variable can be set to the following values: | |
237 | * "0" - don't allow topmost | |
238 | * "1" - allow topmost | |
239 | */ | |
240 | #define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST" | |
241 | ||
242 | ||
243 | /** | |
244 | * \brief A variable that controls the timer resolution, in milliseconds. | |
245 | * | |
246 | * The higher resolution the timer, the more frequently the CPU services | |
247 | * timer interrupts, and the more precise delays are, but this takes up | |
248 | * power and CPU time. This hint is only used on Windows 7 and earlier. | |
249 | * | |
250 | * See this blog post for more information: | |
251 | * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ | |
252 | * | |
253 | * If this variable is set to "0", the system timer resolution is not set. | |
254 | * | |
255 | * The default value is "1". This hint may be set at any time. | |
256 | */ | |
257 | #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" | |
258 | ||
259 | ||
260 | ||
261 | /** | |
262 | * \brief An enumeration of hint priorities | |
263 | */ | |
264 | typedef enum | |
265 | { | |
266 | SDL_HINT_DEFAULT, | |
267 | SDL_HINT_NORMAL, | |
268 | SDL_HINT_OVERRIDE | |
269 | } SDL_HintPriority; | |
270 | ||
271 | ||
272 | /** | |
273 | * \brief Set a hint with a specific priority | |
274 | * | |
275 | * The priority controls the behavior when setting a hint that already | |
276 | * has a value. Hints will replace existing hints of their priority and | |
277 | * lower. Environment variables are considered to have override priority. | |
278 | * | |
279 | * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise | |
280 | */ | |
281 | extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, | |
282 | const char *value, | |
283 | SDL_HintPriority priority); | |
284 | ||
285 | /** | |
286 | * \brief Set a hint with normal priority | |
287 | * | |
288 | * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise | |
289 | */ | |
290 | extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, | |
291 | const char *value); | |
292 | ||
293 | /** | |
294 | * \brief Get a hint | |
295 | * | |
296 | * \return The string value of a hint variable. | |
297 | */ | |
298 | extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); | |
299 | ||
300 | /** | |
301 | * \brief Add a function to watch a particular hint | |
302 | * | |
303 | * \param name The hint to watch | |
304 | * \param callback The function to call when the hint value changes | |
305 | * \param userdata A pointer to pass to the callback function | |
306 | */ | |
307 | typedef void (*SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); | |
308 | extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name, | |
309 | SDL_HintCallback callback, | |
310 | void *userdata); | |
311 | ||
312 | /** | |
313 | * \brief Remove a function watching a particular hint | |
314 | * | |
315 | * \param name The hint being watched | |
316 | * \param callback The function being called when the hint value changes | |
317 | * \param userdata A pointer being passed to the callback function | |
318 | */ | |
319 | extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name, | |
320 | SDL_HintCallback callback, | |
321 | void *userdata); | |
322 | ||
323 | /** | |
324 | * \brief Clear all hints | |
325 | * | |
326 | * This function is called during SDL_Quit() to free stored hints. | |
327 | */ | |
328 | extern DECLSPEC void SDLCALL SDL_ClearHints(void); | |
329 | ||
330 | ||
331 | /* Ends C function definitions when using C++ */ | |
332 | #ifdef __cplusplus | |
333 | } | |
334 | #endif | |
335 | #include "close_code.h" | |
336 | ||
337 | #endif /* _SDL_hints_h */ | |
338 | ||
339 | /* vi: set ts=4 sw=4 expandtab: */ |