Mercurial > sdl-ios-xcode

annotate include/SDL_hints.h @ 5193:82a48f4d65f6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
author Sam Lantinga <slouken@libsdl.org>
date Sat, 05 Feb 2011 10:03:12 -0800
parents 6f6a9340fb93
children ef5a61ea3202
rev   line source
5192
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
1 /*
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
2 SDL - Simple DihintsMedia Layer
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
3 Copyright (C) 1997-2010 Sam Lantinga
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
4
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
5 This library is free software; you can redistribute it and/or
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
6 modify it under the terms of the GNU Lesser General Public
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
7 License as published by the Free Software Foundation; either
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
8 version 2.1 of the License, or (at your option) any later version.
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
9
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
10 This library is distributed in the hope that it will be useful,
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
13 Lesser General Public License for more details.
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
14
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
15 You should have received a copy of the GNU Lesser General Public
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
16 License along with this library; if not, write to the Free Software
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
17 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
18
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
19 Sam Lantinga
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
20 slouken@libsdl.org
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
21 */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
22
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
23 /**
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
24 * \file SDL_hints.h
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
25 *
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
26 * Official documentation for SDL configuration variables
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
27 *
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
28 * This file contains functions to set and get configuration hints,
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
29 * as well as listing each of them alphabetically.
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
30 *
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
31 * The convention for naming hints is SDL_HINT_X, where "SDL_X" is
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
32 * the environment variable that can be used to override the default.
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
33 *
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
34 * In general these hints are just that - they may or may not be
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
35 * supported or applicable on any given platform, but they provide
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
36 * a way for an application or user to give the library a hint as
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
37 * to how they would like the library to work.
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
38 */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
39
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
40 #ifndef _SDL_hints_h
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
41 #define _SDL_hints_h
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
42
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
43 #include "SDL_stdinc.h"
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
44
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
45 #include "begin_code.h"
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
46 /* Set up for C function definitions, even when using C++ */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
47 #ifdef __cplusplus
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
48 /* *INDENT-OFF* */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
49 extern "C" {
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
50 /* *INDENT-ON* */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
51 #endif
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
52
5193
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
53 /**
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
54 * \brief A variable controlling how 3D acceleration is used to accelerate the SDL 1.2 screen surface.
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
55 *
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
56 * SDL can try to accelerate the SDL 1.2 screen surface by using streaming
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
57 * textures with a 3D rendering engine. This variable controls whether and
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
58 * how this is done.
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
59 *
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
60 * This variable can be set to the following values:
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
61 * "0" - Disable 3D acceleration
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
62 * "1" - Enable 3D acceleration, using the default renderer.
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
63 * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.)
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
64 *
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
65 * By default SDL tries to make a best guess for each platform whether
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
66 * to use acceleration or not.
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
67 */
82a48f4d65f6 Added a hint to determine whether framebuffer texture acceleration should be used, and added default behaviors for the various platforms.
Sam Lantinga <slouken@libsdl.org>
parents: 5192
diff changeset
68 #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION"
5192
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
69
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
70
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
71 /**
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
72 * \brief An enumeration of hint priorities
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
73 */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
74 typedef enum
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
75 {
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
76 SDL_HINT_DEFAULT,
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
77 SDL_HINT_NORMAL,
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
78 SDL_HINT_OVERRIDE
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
79 } SDL_HintPriority;
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
80
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
81
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
82 /**
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
83 * \brief Set a hint
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
84 *
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
85 * The priority controls the behavior when setting a hint that already
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
86 * has a value. Hints will replace existing hints of their priority and
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
87 * lower. Environment variables are considered to have override priority.
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
88 *
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
89 * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
90 */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
91 extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
92 const char *value,
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
93 SDL_HintPriority priority);
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
94
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
95 /**
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
96 * \brief Get a hint
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
97 *
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
98 * \return The string value of a hint variable.
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
99 */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
100 extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
101
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
102 /**
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
103 * \brief Clear all hints
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
104 *
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
105 * This function is called during SDL_Quit() to free stored hints.
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
106 */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
107 extern DECLSPEC void SDLCALL SDL_ClearHints();
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
108
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
109
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
110 /* Ends C function definitions when using C++ */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
111 #ifdef __cplusplus
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
112 /* *INDENT-OFF* */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
113 }
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
114 /* *INDENT-ON* */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
115 #endif
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
116 #include "close_code.h"
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
117
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
118 #endif /* _SDL_hints_h */
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
119
6f6a9340fb93 Added a hint system to allow configuration hints to be specified by the application.
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
120 /* vi: set ts=4 sw=4 expandtab: */