Changeset 33098 in project


Ignore:
Timestamp:
01/19/16 23:16:33 (4 years ago)
Author:
John Croisant
Message:

sdl2: Started documenting changes in 0.2.0 (hints and egg-version).

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sdl2

    r33082 r33098  
    144144== Version History
    145145
     146; 0.2.0 (in development) : Improved integer type checking. Added 2D accelerated rendering (renderer and texture). Added hints. Performance improvements. Miscellaneous other changes.
    146147; 0.1.1 (2015-12-22) : Fixed a compile error when compiling with GCC 4.
    147148; 0.1.0 (2015-12-19) : Initial release.
     
    18971898
    18981899
     1900=== Hints
     1901
     1902[[https://wiki.libsdl.org/CategoryHints|Hints (aka Configuration Variables)]]
     1903are a way for you to give hints to the SDL library about how you would like it to behave.
     1904Most hints affect platform-specific behavior.
     1905Hints are merely suggestions, and SDL may or may not obey them.
     1906
     1907Hints can also be specified or overriden by environment variables.
     1908This allows the user to configure SDL to work best on their system.
     1909Usually the environment variable is similar to the SDL constant name,
     1910but prefixed with "SDL_" instead of "SDL_HINT_".
     1911For more information see [[https://hg.libsdl.org/SDL/file/default/include/SDL_hints.h|SDL_hints.h]].
     1912
     1913Procedures for getting and setting hints is available in '''sdl2 egg version 0.2.0 and later'''.
     1914But, SDL will notice environment variables even if you are using an earlier version of the sdl2 egg.
     1915
     1916The tables below list the hint name symbol,
     1917which you can pass to {{get-hint}} and {{set-hint!}},
     1918and the corresponding SDL constant.
     1919See the linked documentation for more information about what the hint does,
     1920and valid values for the hint.
     1921
     1922Some hints are only effective after a certain version of SDL.
     1923You may safely set the hint with any version of SDL,
     1924but it will have no effect on older versions of SDL.
     1925
     1926==== Hints in SDL 2.0.0 and later
     1927
     1928<table>
     1929  <tr>
     1930    <th>Hint name symbol</th>
     1931    <th>SDL constant name</th>
     1932  </tr>
     1933  <tr>
     1934    <td>framebuffer-acceleration</td>
     1935    <td>[[https://wiki.libsdl.org/SDL_HINT_FRAMEBUFFER_ACCELERATION|SDL_HINT_FRAMEBUFFER_ACCELERATION]]</td>
     1936  </tr>
     1937  <tr>
     1938    <td>gamecontrollerconfig</td>
     1939    <td>[[https://wiki.libsdl.org/SDL_HINT_GAMECONTROLLERCONFIG|SDL_HINT_GAMECONTROLLERCONFIG]]</td>
     1940  </tr>
     1941  <tr>
     1942    <td>grab-keyboard</td>
     1943    <td>[[https://wiki.libsdl.org/SDL_HINT_GRAB_KEYBOARD|SDL_HINT_GRAB_KEYBOARD]]</td>
     1944  </tr>
     1945  <tr>
     1946    <td>idle-timer-disabled</td>
     1947    <td>[[https://wiki.libsdl.org/SDL_HINT_IDLE_TIMER_DISABLED|SDL_HINT_IDLE_TIMER_DISABLED]]</td>
     1948  </tr>
     1949  <tr>
     1950    <td>joystick-allow-background-events</td>
     1951    <td>[[https://wiki.libsdl.org/SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS|SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS]]</td>
     1952  </tr>
     1953  <tr>
     1954    <td>orientations</td>
     1955    <td>[[https://wiki.libsdl.org/SDL_HINT_ORIENTATIONS|SDL_HINT_ORIENTATIONS]]</td>
     1956  </tr>
     1957  <tr>
     1958    <td>render-driver</td>
     1959    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_DRIVER|SDL_HINT_RENDER_DRIVER]]</td>
     1960  </tr>
     1961  <tr>
     1962    <td>render-opengl-shaders</td>
     1963    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_OPENGL_SHADERS|SDL_HINT_RENDER_OPENGL_SHADERS]]</td>
     1964  </tr>
     1965  <tr>
     1966    <td>render-scale-quality</td>
     1967    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_SCALE_QUALITY|SDL_HINT_RENDER_SCALE_QUALITY]]</td>
     1968  </tr>
     1969  <tr>
     1970    <td>render-vsync</td>
     1971    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_VSYNC|SDL_HINT_RENDER_VSYNC]]</td>
     1972  </tr>
     1973  <tr>
     1974    <td>timer-resolution</td>
     1975    <td>[[https://wiki.libsdl.org/SDL_HINT_TIMER_RESOLUTION|SDL_HINT_TIMER_RESOLUTION]]</td>
     1976  </tr>
     1977  <tr>
     1978    <td>video-minimize-on-focus-loss</td>
     1979    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS|SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS]]</td>
     1980  </tr>
     1981  <tr>
     1982    <td>video-x11-xinerama</td>
     1983    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_XINERAMA|SDL_HINT_VIDEO_X11_XINERAMA]]</td>
     1984  </tr>
     1985  <tr>
     1986    <td>video-x11-xrandr</td>
     1987    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_XRANDR|SDL_HINT_VIDEO_X11_XRANDR]]</td>
     1988  </tr>
     1989  <tr>
     1990    <td>video-x11-xvidmode</td>
     1991    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_XVIDMODE|SDL_HINT_VIDEO_X11_XVIDMODE]]</td>
     1992  </tr>
     1993  <tr>
     1994    <td>xinput-enabled</td>
     1995    <td>[[https://wiki.libsdl.org/SDL_HINT_XINPUT_ENABLED|SDL_HINT_XINPUT_ENABLED]]</td>
     1996  </tr>
     1997</table>
     1998
     1999==== Hints in SDL 2.0.1 and later
     2000
     2001<table>
     2002  <tr>
     2003    <th>Hint name symbol</th>
     2004    <th>SDL constant name</th>
     2005  </tr>
     2006  <tr>
     2007    <td>render-direct3d-threadsafe</td>
     2008    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_DIRECT3D_THREADSAFE|SDL_HINT_RENDER_DIRECT3D_THREADSAFE]]</td>
     2009  </tr>
     2010  <tr>
     2011    <td>video-highdpi-disabled</td>
     2012    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_HIGHDPI_DISABLED|SDL_HINT_VIDEO_HIGHDPI_DISABLED]]</td>
     2013  </tr>
     2014</table>
     2015
     2016
     2017==== Hints in SDL 2.0.2 and later
     2018
     2019<table>
     2020  <tr>
     2021    <th>Hint name symbol</th>
     2022    <th>SDL constant name</th>
     2023  </tr>
     2024  <tr>
     2025    <td>accelerometer-as-joystick</td>
     2026    <td>[[https://wiki.libsdl.org/SDL_HINT_ACCELEROMETER_AS_JOYSTICK|SDL_HINT_ACCELEROMETER_AS_JOYSTICK]]</td>
     2027  </tr>
     2028  <tr>
     2029    <td>mac-ctrl-click-emulate-right-click</td>
     2030    <td>[[https://wiki.libsdl.org/SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK|SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK]]</td>
     2031  </tr>
     2032  <tr>
     2033    <td>mouse-relative-mode-warp</td>
     2034    <td>[[https://wiki.libsdl.org/SDL_HINT_MOUSE_RELATIVE_MODE_WARP|SDL_HINT_MOUSE_RELATIVE_MODE_WARP]]</td>
     2035  </tr>
     2036  <tr>
     2037    <td>video-allow-screensaver</td>
     2038    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_ALLOW_SCREENSAVER|SDL_HINT_VIDEO_ALLOW_SCREENSAVER]]</td>
     2039  </tr>
     2040  <tr>
     2041    <td>video-mac-fullscreen-spaces</td>
     2042    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES|SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES]]</td>
     2043  </tr>
     2044  <tr>
     2045    <td>video-window-share-pixel-format</td>
     2046    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT|SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT]]</td>
     2047  </tr>
     2048  <tr>
     2049    <td>video-win-d3dcompiler</td>
     2050    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_WIN_D3DCOMPILER|SDL_HINT_VIDEO_WIN_D3DCOMPILER]]</td>
     2051  </tr>
     2052</table>
     2053
     2054
     2055==== Hints in SDL 2.0.3 and later
     2056
     2057<table>
     2058  <tr>
     2059    <th>Hint name symbol</th>
     2060    <th>SDL constant name</th>
     2061  </tr>
     2062  <tr>
     2063    <td>render-direct3d11-debug</td>
     2064    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_DIRECT3D11_DEBUG|SDL_HINT_RENDER_DIRECT3D11_DEBUG]]</td>
     2065  </tr>
     2066  <tr>
     2067    <td>winrt-handle-back-button</td>
     2068    <td>[[https://wiki.libsdl.org/SDL_HINT_WINRT_HANDLE_BACK_BUTTON|SDL_HINT_WINRT_HANDLE_BACK_BUTTON]]</td>
     2069  </tr>
     2070  <tr>
     2071    <td>winrt-privacy-policy-label</td>
     2072    <td>[[https://wiki.libsdl.org/SDL_HINT_WINRT_PRIVACY_POLICY_LABEL|SDL_HINT_WINRT_PRIVACY_POLICY_LABEL]]</td>
     2073  </tr>
     2074  <tr>
     2075    <td>winrt-privacy-policy-url</td>
     2076    <td>[[https://wiki.libsdl.org/SDL_HINT_WINRT_PRIVACY_POLICY_URL|SDL_HINT_WINRT_PRIVACY_POLICY_URL]]</td>
     2077  </tr>
     2078</table>
     2079
     2080
     2081==== Hints in SDL 2.0.4 and later
     2082
     2083<table>
     2084  <tr>
     2085    <th>Hint name symbol</th>
     2086    <th>SDL constant name</th>
     2087  </tr>
     2088  <tr>
     2089    <td>android-apk-expansion-main-file-version</td>
     2090    <td>[[https://wiki.libsdl.org/SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION|SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION]]</td>
     2091  </tr>
     2092  <tr>
     2093    <td>android-apk-expansion-patch-file-version</td>
     2094    <td>[[https://wiki.libsdl.org/SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION|SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION]]</td>
     2095  </tr>
     2096  <tr>
     2097    <td>android-separate-mouse-and-touch</td>
     2098    <td>[[https://wiki.libsdl.org/SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH|SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH]]</td>
     2099  </tr>
     2100  <tr>
     2101    <td>emscripten-keyboard-element</td>
     2102    <td>[[https://wiki.libsdl.org/SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT|SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT]]</td>
     2103  </tr>
     2104  <tr>
     2105    <td>ime-internal-editing</td>
     2106    <td>[[https://wiki.libsdl.org/SDL_HINT_IME_INTERNAL_EDITING|SDL_HINT_IME_INTERNAL_EDITING]]</td>
     2107  </tr>
     2108  <tr>
     2109    <td>mac-background-app</td>
     2110    <td>[[https://wiki.libsdl.org/SDL_HINT_MAC_BACKGROUND_APP|SDL_HINT_MAC_BACKGROUND_APP]]</td>
     2111  </tr>
     2112  <tr>
     2113    <td>no-signal-handlers</td>
     2114    <td>[[https://wiki.libsdl.org/SDL_HINT_NO_SIGNAL_HANDLERS|SDL_HINT_NO_SIGNAL_HANDLERS]]</td>
     2115  </tr>
     2116  <tr>
     2117    <td>thread-stack-size</td>
     2118    <td>[[https://wiki.libsdl.org/SDL_HINT_THREAD_STACK_SIZE|SDL_HINT_THREAD_STACK_SIZE]]</td>
     2119  </tr>
     2120  <tr>
     2121    <td>video-x11-net-wm-ping</td>
     2122    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_NET_WM_PING|SDL_HINT_VIDEO_X11_NET_WM_PING]]</td>
     2123  </tr>
     2124  <tr>
     2125    <td>windows-enable-messageloop</td>
     2126    <td>[[https://wiki.libsdl.org/SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP|SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP]]</td>
     2127  </tr>
     2128  <tr>
     2129    <td>windows-no-close-on-alt-f4</td>
     2130    <td>[[https://wiki.libsdl.org/SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4|SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4]]</td>
     2131  </tr>
     2132  <tr>
     2133    <td>window-frame-usable-while-cursor-hidden</td>
     2134    <td>[[https://wiki.libsdl.org/SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN|SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN]]</td>
     2135  </tr>
     2136  <tr>
     2137    <td>xinput-use-old-joystick-mapping</td>
     2138    <td>[[https://wiki.libsdl.org/SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING|SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING]]</td>
     2139  </tr>
     2140</table>
     2141
     2142==== Hint Functions
     2143
     2144<procedure>(get-hint name) → string or #f</procedure>
     2145
     2146Returns the current value of the hint as a string, or #f if the hint has no value.
     2147See [[https://wiki.libsdl.org/SDL_GetHint|SDL_GetHint]].
     2148This procedure is available in '''sdl2 egg version 0.2.0 and later'''.
     2149
     2150
     2151<procedure>(set-hint! name value #!optional priority) → boolean</procedure>
     2152
     2153Sets the value of the hint.
     2154See [[https://wiki.libsdl.org/SDL_SetHintWithPriority|SDL_SetHintWithPriority]].
     2155This procedure is available in '''sdl2 egg version 0.2.0 and later'''.
     2156
     2157{{name}} specifies which hint to change.
     2158It must be a symbol from the tables above, or a string.
     2159This procedure signals an exception if {{name}} is an unrecognized symbol
     2160(i.e. is not listed in any of the tables above).
     2161This procedures accepts any string name, even if it is not recognized.
     2162
     2163{{value}} specifies the new value of the hint. It must be a string.
     2164
     2165{{priority}} specifies the priorily level for setting the hint.
     2166If it is omitted, the priority will be {{'normal}}.
     2167It must be one of these symbols:
     2168
     2169* {{'default}}
     2170* {{'normal}}
     2171* {{'override}}
     2172
     2173Returns #t if the hint's value was changed, or #f if it was not changed
     2174(e.g. because the hint was already set with a higher priority).
     2175
     2176
     2177<procedure>(clear-hints!)</procedure>
     2178
     2179Removes the values and priorities of all hints.
     2180See [[https://wiki.libsdl.org/SDL_ClearHints|SDL_ClearHints]].
     2181This procedure is available in '''sdl2 egg version 0.2.0 and later'''.
     2182
     2183
     2184
    18992185=== Joystick
    19002186
     
    35023788See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]]
    35033789and [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]].
     3790
     3791
     3792<constant>(egg-version) → list of integers</constant>
     3793
     3794Returns a list of three nonnegative integers, indicating the version number of the sdl2 egg itself, which is independent of the version number of SDL.
     3795For example, the list {{'(1 2 3)}} indicates sdl2 egg version 1.2.3.
     3796
     3797'''NOTE:''' This procedure is available in '''sdl2 egg version 0.2.0 or later'''.
     3798If you want to check the egg version, but users of your program might be using earlier than egg version 0.2.0,
     3799you can define and use the following procedure in your program:
     3800
     3801<enscript highlight="scheme">
     3802;; Return sdl2 egg version if possible, otherwise return '(0 1 0).
     3803(define (get-sdl2-egg-version)
     3804  (condition-case (sdl2#egg-version)
     3805    (() '(0 1 0))))
     3806</enscript>
    35043807
    35053808
Note: See TracChangeset for help on using the changeset viewer.