ruby2d 0.11.0 → 0.11.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (404) hide show
  1. checksums.yaml +4 -4
  2. data/assets/include/SDL2/SDL.h +108 -14
  3. data/assets/include/SDL2/SDL_assert.h +81 -50
  4. data/assets/include/SDL2/SDL_atomic.h +135 -35
  5. data/assets/include/SDL2/SDL_audio.h +960 -355
  6. data/assets/include/SDL2/SDL_bits.h +11 -6
  7. data/assets/include/SDL2/SDL_blendmode.h +91 -14
  8. data/assets/include/SDL2/SDL_clipboard.h +30 -7
  9. data/assets/include/SDL2/SDL_config.h +3 -1
  10. data/assets/include/SDL2/SDL_config_android.h +11 -1
  11. data/assets/include/SDL2/SDL_config_emscripten.h +216 -0
  12. data/assets/include/SDL2/SDL_config_iphoneos.h +9 -1
  13. data/assets/include/SDL2/SDL_config_macosx.h +16 -2
  14. data/assets/include/SDL2/SDL_config_minimal.h +4 -1
  15. data/assets/include/SDL2/SDL_config_os2.h +37 -20
  16. data/assets/include/SDL2/SDL_config_pandora.h +6 -1
  17. data/assets/include/SDL2/SDL_config_psp.h +8 -8
  18. data/assets/include/SDL2/SDL_config_windows.h +39 -22
  19. data/assets/include/SDL2/SDL_config_winrt.h +23 -8
  20. data/assets/include/SDL2/SDL_config_wiz.h +6 -1
  21. data/assets/include/SDL2/SDL_copying.h +1 -1
  22. data/assets/include/SDL2/SDL_cpuinfo.h +331 -71
  23. data/assets/include/SDL2/SDL_egl.h +906 -280
  24. data/assets/include/SDL2/SDL_endian.h +101 -47
  25. data/assets/include/SDL2/SDL_error.h +70 -19
  26. data/assets/include/SDL2/SDL_events.h +387 -79
  27. data/assets/include/SDL2/SDL_filesystem.h +73 -64
  28. data/assets/include/SDL2/SDL_gamecontroller.h +585 -125
  29. data/assets/include/SDL2/SDL_gesture.h +36 -6
  30. data/assets/include/SDL2/SDL_haptic.h +304 -210
  31. data/assets/include/SDL2/SDL_hidapi.h +451 -0
  32. data/assets/include/SDL2/SDL_hints.h +1286 -897
  33. data/assets/include/SDL2/SDL_joystick.h +577 -130
  34. data/assets/include/SDL2/SDL_keyboard.h +162 -63
  35. data/assets/include/SDL2/SDL_keycode.h +7 -5
  36. data/assets/include/SDL2/SDL_loadso.h +42 -8
  37. data/assets/include/SDL2/SDL_locale.h +34 -32
  38. data/assets/include/SDL2/SDL_log.h +212 -19
  39. data/assets/include/SDL2/SDL_main.h +72 -17
  40. data/assets/include/SDL2/SDL_messagebox.h +70 -23
  41. data/assets/include/SDL2/SDL_metal.h +27 -32
  42. data/assets/include/SDL2/SDL_misc.h +19 -15
  43. data/assets/include/SDL2/SDL_mouse.h +262 -110
  44. data/assets/include/SDL2/SDL_mutex.h +286 -66
  45. data/assets/include/SDL2/SDL_name.h +1 -1
  46. data/assets/include/SDL2/SDL_opengl.h +1 -1
  47. data/assets/include/SDL2/SDL_opengles.h +1 -1
  48. data/assets/include/SDL2/SDL_opengles2.h +2 -2
  49. data/assets/include/SDL2/SDL_pixels.h +199 -34
  50. data/assets/include/SDL2/SDL_platform.h +39 -2
  51. data/assets/include/SDL2/SDL_power.h +23 -10
  52. data/assets/include/SDL2/SDL_quit.h +1 -1
  53. data/assets/include/SDL2/SDL_rect.h +78 -28
  54. data/assets/include/SDL2/SDL_render.h +1204 -472
  55. data/assets/include/SDL2/SDL_revision.h +2 -2
  56. data/assets/include/SDL2/SDL_rwops.h +605 -33
  57. data/assets/include/SDL2/SDL_scancode.h +1 -1
  58. data/assets/include/SDL2/SDL_sensor.h +76 -42
  59. data/assets/include/SDL2/SDL_shape.h +38 -27
  60. data/assets/include/SDL2/SDL_stdinc.h +96 -24
  61. data/assets/include/SDL2/SDL_surface.h +571 -139
  62. data/assets/include/SDL2/SDL_system.h +339 -101
  63. data/assets/include/SDL2/SDL_syswm.h +50 -20
  64. data/assets/include/SDL2/SDL_test.h +1 -1
  65. data/assets/include/SDL2/SDL_test_assert.h +2 -2
  66. data/assets/include/SDL2/SDL_test_common.h +23 -6
  67. data/assets/include/SDL2/SDL_test_compare.h +1 -1
  68. data/assets/include/SDL2/SDL_test_crc32.h +1 -1
  69. data/assets/include/SDL2/SDL_test_font.h +3 -3
  70. data/assets/include/SDL2/SDL_test_fuzzer.h +28 -26
  71. data/assets/include/SDL2/SDL_test_harness.h +6 -6
  72. data/assets/include/SDL2/SDL_test_images.h +1 -1
  73. data/assets/include/SDL2/SDL_test_log.h +1 -1
  74. data/assets/include/SDL2/SDL_test_md5.h +1 -1
  75. data/assets/include/SDL2/SDL_test_memory.h +1 -1
  76. data/assets/include/SDL2/SDL_test_random.h +2 -2
  77. data/assets/include/SDL2/SDL_thread.h +226 -128
  78. data/assets/include/SDL2/SDL_timer.h +129 -22
  79. data/assets/include/SDL2/SDL_touch.h +48 -8
  80. data/assets/include/SDL2/SDL_ttf.h +102 -9
  81. data/assets/include/SDL2/SDL_types.h +1 -1
  82. data/assets/include/SDL2/SDL_version.h +72 -46
  83. data/assets/include/SDL2/SDL_video.h +1266 -460
  84. data/assets/include/SDL2/SDL_vulkan.h +100 -161
  85. data/assets/include/SDL2/begin_code.h +22 -1
  86. data/assets/include/SDL2/close_code.h +1 -1
  87. data/assets/include/mrbconf.h +234 -0
  88. data/assets/include/mruby/array.h +317 -0
  89. data/assets/include/mruby/boxing_nan.h +130 -0
  90. data/assets/include/mruby/boxing_no.h +58 -0
  91. data/assets/include/mruby/boxing_word.h +205 -0
  92. data/assets/include/mruby/class.h +108 -0
  93. data/assets/include/mruby/common.h +92 -0
  94. data/assets/include/mruby/compile.h +210 -0
  95. data/assets/include/mruby/data.h +76 -0
  96. data/assets/include/mruby/debug.h +66 -0
  97. data/assets/include/mruby/dump.h +158 -0
  98. data/assets/include/mruby/endian.h +44 -0
  99. data/assets/include/mruby/error.h +137 -0
  100. data/assets/include/mruby/gc.h +92 -0
  101. data/assets/include/mruby/hash.h +242 -0
  102. data/assets/include/mruby/irep.h +147 -0
  103. data/assets/include/mruby/istruct.h +50 -0
  104. data/assets/include/mruby/khash.h +284 -0
  105. data/assets/include/mruby/numeric.h +169 -0
  106. data/assets/include/mruby/object.h +43 -0
  107. data/assets/include/mruby/opcode.h +43 -0
  108. data/assets/include/mruby/ops.h +122 -0
  109. data/assets/include/mruby/presym/disable.h +70 -0
  110. data/assets/include/mruby/presym/enable.h +37 -0
  111. data/assets/include/mruby/presym/scanning.h +73 -0
  112. data/assets/include/mruby/presym.h +40 -0
  113. data/assets/include/mruby/proc.h +209 -0
  114. data/assets/include/mruby/range.h +79 -0
  115. data/assets/include/mruby/re.h +16 -0
  116. data/assets/include/mruby/string.h +469 -0
  117. data/assets/include/mruby/throw.h +66 -0
  118. data/assets/include/mruby/value.h +400 -0
  119. data/assets/include/mruby/variable.h +140 -0
  120. data/assets/include/mruby/version.h +143 -0
  121. data/assets/include/mruby.h +1444 -0
  122. data/assets/macos/universal/bin/mrbc +0 -0
  123. data/assets/macos/universal/lib/libFLAC.a +0 -0
  124. data/assets/macos/universal/lib/libSDL2.a +0 -0
  125. data/assets/macos/universal/lib/libSDL2_image.a +0 -0
  126. data/assets/macos/{lib → universal/lib}/libSDL2_mixer.a +0 -0
  127. data/assets/macos/universal/lib/libSDL2_ttf.a +0 -0
  128. data/assets/macos/universal/lib/libfreetype.a +0 -0
  129. data/assets/macos/universal/lib/libgraphite2.a +0 -0
  130. data/assets/macos/universal/lib/libharfbuzz.a +0 -0
  131. data/assets/macos/universal/lib/libjpeg.a +0 -0
  132. data/assets/macos/universal/lib/libmodplug.a +0 -0
  133. data/assets/macos/{lib → universal/lib}/libmpg123.a +0 -0
  134. data/assets/{mingw/lib/libSDL2.a → macos/universal/lib/libmruby.a} +0 -0
  135. data/assets/macos/{lib → universal/lib}/libogg.a +0 -0
  136. data/assets/macos/universal/lib/libpng16.a +0 -0
  137. data/assets/macos/universal/lib/libtiff.a +0 -0
  138. data/assets/macos/universal/lib/libvorbis.a +0 -0
  139. data/assets/macos/universal/lib/libvorbisfile.a +0 -0
  140. data/assets/macos/universal/lib/libwebp.a +0 -0
  141. data/assets/test_media/README.md +3 -0
  142. data/assets/test_media/bitstream_vera/COPYRIGHT.txt +124 -0
  143. data/assets/test_media/bitstream_vera/vera.ttf +0 -0
  144. data/assets/test_media/boom.png +0 -0
  145. data/assets/test_media/coin.png +0 -0
  146. data/assets/test_media/colors.png +0 -0
  147. data/assets/test_media/controller.png +0 -0
  148. data/assets/test_media/dial.wav +0 -0
  149. data/assets/test_media/hero.png +0 -0
  150. data/assets/test_media/image.bmp +0 -0
  151. data/assets/test_media/image.jpg +0 -0
  152. data/assets/test_media/image.png +0 -0
  153. data/assets/test_media/music.flac +0 -0
  154. data/assets/test_media/music.mp3 +0 -0
  155. data/assets/test_media/music.ogg +0 -0
  156. data/assets/test_media/music.wav +0 -0
  157. data/assets/test_media/originals/boom.pxm +0 -0
  158. data/assets/test_media/originals/coin.pxm +0 -0
  159. data/assets/test_media/originals/controller.sketch +0 -0
  160. data/assets/test_media/originals/hero.pxm +0 -0
  161. data/assets/test_media/originals/image.pxm +0 -0
  162. data/assets/test_media/originals/music.caf +0 -0
  163. data/assets/test_media/originals/texture_atlas.pxm +0 -0
  164. data/assets/test_media/rondo_alla_turka.ogg +0 -0
  165. data/assets/test_media/sound.flac +0 -0
  166. data/assets/test_media/sound.mp3 +0 -0
  167. data/assets/test_media/sound.ogg +0 -0
  168. data/assets/test_media/sound.wav +0 -0
  169. data/assets/test_media/sprite_sheet.png +0 -0
  170. data/assets/test_media/texture_atlas.png +0 -0
  171. data/assets/wasm/libmruby.a +0 -0
  172. data/assets/wasm/template.html +64 -0
  173. data/assets/windows/glew/README.md +10 -0
  174. data/assets/windows/glew/glew.h +23686 -0
  175. data/assets/{mingw/lib → windows/glew}/libglew32.a +0 -0
  176. data/assets/windows/mingw-w64-ucrt-x86_64/bin/mrbc.exe +0 -0
  177. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libFLAC.a +0 -0
  178. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libLerc.a +0 -0
  179. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2.a +0 -0
  180. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2_image.a +0 -0
  181. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2_mixer.a +0 -0
  182. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2_ttf.a +0 -0
  183. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libbrotlicommon.a +0 -0
  184. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libbrotlidec.a +0 -0
  185. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libbz2.a +0 -0
  186. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libdeflate.a +0 -0
  187. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libfreetype.a +0 -0
  188. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libglew32.a +0 -0
  189. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libgraphite2.a +0 -0
  190. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libharfbuzz.a +0 -0
  191. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libjbig.a +0 -0
  192. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libjpeg.a +0 -0
  193. data/assets/windows/mingw-w64-ucrt-x86_64/lib/liblzma.a +0 -0
  194. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libmodplug.a +0 -0
  195. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libmpg123.a +0 -0
  196. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libmruby.a +0 -0
  197. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libogg.a +0 -0
  198. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libopus.a +0 -0
  199. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libopusfile.a +0 -0
  200. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libpng16.a +0 -0
  201. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libsndfile.a +0 -0
  202. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libssp.a +0 -0
  203. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libstdc++.a +0 -0
  204. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libtiff.a +0 -0
  205. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libvorbis.a +0 -0
  206. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libvorbisfile.a +0 -0
  207. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libwebp.a +0 -0
  208. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libz.a +0 -0
  209. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libzstd.a +0 -0
  210. data/assets/windows/mingw-w64-x86_64/bin/mrbc.exe +0 -0
  211. data/assets/windows/mingw-w64-x86_64/lib/libFLAC.a +0 -0
  212. data/assets/windows/mingw-w64-x86_64/lib/libLerc.a +0 -0
  213. data/assets/windows/mingw-w64-x86_64/lib/libSDL2.a +0 -0
  214. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_image.a +0 -0
  215. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_mixer.a +0 -0
  216. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_ttf.a +0 -0
  217. data/assets/windows/mingw-w64-x86_64/lib/libbrotlicommon.a +0 -0
  218. data/assets/windows/mingw-w64-x86_64/lib/libbrotlidec.a +0 -0
  219. data/assets/windows/mingw-w64-x86_64/lib/libbz2.a +0 -0
  220. data/assets/windows/mingw-w64-x86_64/lib/libdeflate.a +0 -0
  221. data/assets/windows/mingw-w64-x86_64/lib/libfreetype.a +0 -0
  222. data/assets/windows/mingw-w64-x86_64/lib/libglew32.a +0 -0
  223. data/assets/windows/mingw-w64-x86_64/lib/libgraphite2.a +0 -0
  224. data/assets/windows/mingw-w64-x86_64/lib/libharfbuzz.a +0 -0
  225. data/assets/windows/mingw-w64-x86_64/lib/libjbig.a +0 -0
  226. data/assets/windows/mingw-w64-x86_64/lib/libjpeg.a +0 -0
  227. data/assets/windows/mingw-w64-x86_64/lib/liblzma.a +0 -0
  228. data/assets/windows/mingw-w64-x86_64/lib/libmodplug.a +0 -0
  229. data/assets/windows/mingw-w64-x86_64/lib/libmpg123.a +0 -0
  230. data/assets/windows/mingw-w64-x86_64/lib/libmruby.a +0 -0
  231. data/assets/windows/mingw-w64-x86_64/lib/libogg.a +0 -0
  232. data/assets/windows/mingw-w64-x86_64/lib/libopus.a +0 -0
  233. data/assets/windows/mingw-w64-x86_64/lib/libopusfile.a +0 -0
  234. data/assets/windows/mingw-w64-x86_64/lib/libpng16.a +0 -0
  235. data/assets/windows/mingw-w64-x86_64/lib/libsndfile.a +0 -0
  236. data/assets/windows/mingw-w64-x86_64/lib/libssp.a +0 -0
  237. data/assets/windows/mingw-w64-x86_64/lib/libstdc++.a +0 -0
  238. data/assets/windows/mingw-w64-x86_64/lib/libtiff.a +0 -0
  239. data/assets/windows/mingw-w64-x86_64/lib/libvorbis.a +0 -0
  240. data/assets/windows/mingw-w64-x86_64/lib/libvorbisfile.a +0 -0
  241. data/assets/windows/mingw-w64-x86_64/lib/libwebp.a +0 -0
  242. data/assets/windows/mingw-w64-x86_64/lib/libz.a +0 -0
  243. data/assets/windows/mingw-w64-x86_64/lib/libzstd.a +0 -0
  244. data/assets/{ios → xcode/ios}/Assets.xcassets/AppIcon.appiconset/Contents.json +0 -0
  245. data/assets/{ios → xcode/ios}/Assets.xcassets/Contents.json +0 -0
  246. data/assets/{ios → xcode/ios}/Base.lproj/LaunchScreen.storyboard +0 -0
  247. data/assets/{ios → xcode/ios}/Info.plist +0 -0
  248. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mrbconf.h +0 -0
  249. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/array.h +0 -0
  250. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/boxing_nan.h +0 -0
  251. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/boxing_no.h +0 -0
  252. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/boxing_word.h +0 -0
  253. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/class.h +0 -0
  254. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/common.h +0 -0
  255. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/compile.h +0 -0
  256. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/data.h +0 -0
  257. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/debug.h +0 -0
  258. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/dump.h +0 -0
  259. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/error.h +0 -0
  260. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/gc.h +0 -0
  261. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/hash.h +0 -0
  262. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/irep.h +0 -0
  263. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/istruct.h +0 -0
  264. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/khash.h +0 -0
  265. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/numeric.h +0 -0
  266. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/object.h +0 -0
  267. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/opcode.h +0 -0
  268. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/ops.h +0 -0
  269. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/proc.h +0 -0
  270. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/range.h +0 -0
  271. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/re.h +0 -0
  272. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/string.h +0 -0
  273. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/throw.h +0 -0
  274. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/value.h +0 -0
  275. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/variable.h +0 -0
  276. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/version.h +0 -0
  277. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby.h +0 -0
  278. data/assets/{ios → xcode/ios}/MRuby.framework/Info.plist +0 -0
  279. data/assets/{ios → xcode/ios}/MRuby.framework/MRuby +0 -0
  280. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.pbxproj +0 -0
  281. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.xcworkspace/contents.xcworkspacedata +0 -0
  282. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist +0 -0
  283. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/MyApp.xcscmblueprint +0 -0
  284. data/assets/{ios → xcode/ios}/main.c +0 -0
  285. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Back.imagestacklayer/Content.imageset/Contents.json +0 -0
  286. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Back.imagestacklayer/Contents.json +0 -0
  287. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Contents.json +0 -0
  288. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Front.imagestacklayer/Content.imageset/Contents.json +0 -0
  289. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Front.imagestacklayer/Contents.json +0 -0
  290. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Middle.imagestacklayer/Content.imageset/Contents.json +0 -0
  291. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Middle.imagestacklayer/Contents.json +0 -0
  292. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Back.imagestacklayer/Content.imageset/Contents.json +0 -0
  293. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Back.imagestacklayer/Contents.json +0 -0
  294. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Contents.json +0 -0
  295. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Front.imagestacklayer/Content.imageset/Contents.json +0 -0
  296. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Front.imagestacklayer/Contents.json +0 -0
  297. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Middle.imagestacklayer/Content.imageset/Contents.json +0 -0
  298. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Middle.imagestacklayer/Contents.json +0 -0
  299. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/Contents.json +0 -0
  300. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/Top Shelf Image Wide.imageset/Contents.json +0 -0
  301. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/Top Shelf Image.imageset/Contents.json +0 -0
  302. data/assets/{tvos → xcode/tvos}/Assets.xcassets/Contents.json +0 -0
  303. data/assets/{tvos → xcode/tvos}/Assets.xcassets/LaunchImage.launchimage/Contents.json +0 -0
  304. data/assets/{tvos → xcode/tvos}/Info.plist +0 -0
  305. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mrbconf.h +0 -0
  306. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/array.h +0 -0
  307. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/boxing_nan.h +0 -0
  308. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/boxing_no.h +0 -0
  309. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/boxing_word.h +0 -0
  310. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/class.h +0 -0
  311. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/common.h +0 -0
  312. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/compile.h +0 -0
  313. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/data.h +0 -0
  314. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/debug.h +0 -0
  315. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/dump.h +0 -0
  316. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/error.h +0 -0
  317. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/gc.h +0 -0
  318. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/hash.h +0 -0
  319. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/irep.h +0 -0
  320. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/istruct.h +0 -0
  321. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/khash.h +0 -0
  322. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/numeric.h +0 -0
  323. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/object.h +0 -0
  324. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/opcode.h +0 -0
  325. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/ops.h +0 -0
  326. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/proc.h +0 -0
  327. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/range.h +0 -0
  328. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/re.h +0 -0
  329. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/string.h +0 -0
  330. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/throw.h +0 -0
  331. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/value.h +0 -0
  332. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/variable.h +0 -0
  333. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/version.h +0 -0
  334. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby.h +0 -0
  335. data/assets/{tvos → xcode/tvos}/MRuby.framework/Info.plist +0 -0
  336. data/assets/{tvos → xcode/tvos}/MRuby.framework/MRuby +0 -0
  337. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.pbxproj +0 -0
  338. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.xcworkspace/contents.xcworkspacedata +0 -0
  339. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist +0 -0
  340. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/MyApp.xcscmblueprint +0 -0
  341. data/assets/{tvos → xcode/tvos}/main.c +0 -0
  342. data/bin/ruby2d +3 -4
  343. data/ext/ruby2d/extconf.rb +44 -25
  344. data/ext/ruby2d/gl.c +1 -1
  345. data/ext/ruby2d/gl3.c +0 -1
  346. data/ext/ruby2d/gles.c +137 -84
  347. data/ext/ruby2d/ruby2d.c +126 -32
  348. data/ext/ruby2d/ruby2d.h +53 -6
  349. data/ext/ruby2d/text.c +14 -1
  350. data/ext/ruby2d/window.c +253 -215
  351. data/lib/ruby2d/cli/build.rb +242 -59
  352. data/lib/ruby2d/cli/colorize.rb +5 -4
  353. data/lib/ruby2d/cli/platform.rb +17 -0
  354. data/lib/ruby2d/font.rb +7 -1
  355. data/lib/ruby2d/sprite.rb +7 -2
  356. data/lib/ruby2d/text.rb +1 -3
  357. data/lib/ruby2d/texture.rb +21 -21
  358. data/lib/ruby2d/tileset.rb +34 -33
  359. data/lib/ruby2d/version.rb +1 -1
  360. data/lib/ruby2d/vertices.rb +11 -6
  361. data/lib/ruby2d.rb +14 -20
  362. metadata +279 -151
  363. data/assets/README.md +0 -22
  364. data/assets/Rakefile +0 -85
  365. data/assets/macos/lib/libFLAC.a +0 -0
  366. data/assets/macos/lib/libSDL2.a +0 -0
  367. data/assets/macos/lib/libSDL2_image.a +0 -0
  368. data/assets/macos/lib/libSDL2_ttf.a +0 -0
  369. data/assets/macos/lib/libfreetype.a +0 -0
  370. data/assets/macos/lib/libjpeg.a +0 -0
  371. data/assets/macos/lib/libpng16.a +0 -0
  372. data/assets/macos/lib/libtiff.a +0 -0
  373. data/assets/macos/lib/libvorbis.a +0 -0
  374. data/assets/macos/lib/libvorbisfile.a +0 -0
  375. data/assets/macos/lib/libwebp.a +0 -0
  376. data/assets/mingw/bin/SDL2.dll +0 -0
  377. data/assets/mingw/bin/SDL2_image.dll +0 -0
  378. data/assets/mingw/bin/SDL2_mixer.dll +0 -0
  379. data/assets/mingw/bin/SDL2_ttf.dll +0 -0
  380. data/assets/mingw/bin/glew32.dll +0 -0
  381. data/assets/mingw/bin/libFLAC-8.dll +0 -0
  382. data/assets/mingw/bin/libfreetype-6.dll +0 -0
  383. data/assets/mingw/bin/libjpeg-9.dll +0 -0
  384. data/assets/mingw/bin/libmodplug-1.dll +0 -0
  385. data/assets/mingw/bin/libmpg123-0.dll +0 -0
  386. data/assets/mingw/bin/libogg-0.dll +0 -0
  387. data/assets/mingw/bin/libopus-0.dll +0 -0
  388. data/assets/mingw/bin/libopusfile-0.dll +0 -0
  389. data/assets/mingw/bin/libpng16-16.dll +0 -0
  390. data/assets/mingw/bin/libtiff-5.dll +0 -0
  391. data/assets/mingw/bin/libvorbis-0.dll +0 -0
  392. data/assets/mingw/bin/libvorbisfile-3.dll +0 -0
  393. data/assets/mingw/bin/libwebp-7.dll +0 -0
  394. data/assets/mingw/bin/zlib1.dll +0 -0
  395. data/assets/mingw/lib/libSDL2.dll.a +0 -0
  396. data/assets/mingw/lib/libSDL2_image.a +0 -0
  397. data/assets/mingw/lib/libSDL2_image.dll.a +0 -0
  398. data/assets/mingw/lib/libSDL2_mixer.a +0 -0
  399. data/assets/mingw/lib/libSDL2_mixer.dll.a +0 -0
  400. data/assets/mingw/lib/libSDL2_test.a +0 -0
  401. data/assets/mingw/lib/libSDL2_ttf.a +0 -0
  402. data/assets/mingw/lib/libSDL2_ttf.dll.a +0 -0
  403. data/assets/mingw/lib/libSDL2main.a +0 -0
  404. data/assets/mingw/lib/libglew32.dll.a +0 -0
@@ -1,6 +1,6 @@
1
1
  /*
2
2
  Simple DirectMedia Layer
3
- Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
4
4
 
5
5
  This software is provided 'as-is', without any express or implied
6
6
  warranty. In no event will the authors be held liable for any damages
@@ -65,9 +65,12 @@ typedef struct
65
65
  * \sa SDL_CreateWindow()
66
66
  * \sa SDL_CreateWindowFrom()
67
67
  * \sa SDL_DestroyWindow()
68
+ * \sa SDL_FlashWindow()
68
69
  * \sa SDL_GetWindowData()
69
70
  * \sa SDL_GetWindowFlags()
70
71
  * \sa SDL_GetWindowGrab()
72
+ * \sa SDL_GetWindowKeyboardGrab()
73
+ * \sa SDL_GetWindowMouseGrab()
71
74
  * \sa SDL_GetWindowPosition()
72
75
  * \sa SDL_GetWindowSize()
73
76
  * \sa SDL_GetWindowTitle()
@@ -79,6 +82,8 @@ typedef struct
79
82
  * \sa SDL_SetWindowData()
80
83
  * \sa SDL_SetWindowFullscreen()
81
84
  * \sa SDL_SetWindowGrab()
85
+ * \sa SDL_SetWindowKeyboardGrab()
86
+ * \sa SDL_SetWindowMouseGrab()
82
87
  * \sa SDL_SetWindowIcon()
83
88
  * \sa SDL_SetWindowPosition()
84
89
  * \sa SDL_SetWindowSize()
@@ -104,7 +109,7 @@ typedef enum
104
109
  SDL_WINDOW_RESIZABLE = 0x00000020, /**< window can be resized */
105
110
  SDL_WINDOW_MINIMIZED = 0x00000040, /**< window is minimized */
106
111
  SDL_WINDOW_MAXIMIZED = 0x00000080, /**< window is maximized */
107
- SDL_WINDOW_INPUT_GRABBED = 0x00000100, /**< window has grabbed input focus */
112
+ SDL_WINDOW_MOUSE_GRABBED = 0x00000100, /**< window has grabbed mouse input */
108
113
  SDL_WINDOW_INPUT_FOCUS = 0x00000200, /**< window has input focus */
109
114
  SDL_WINDOW_MOUSE_FOCUS = 0x00000400, /**< window has mouse focus */
110
115
  SDL_WINDOW_FULLSCREEN_DESKTOP = ( SDL_WINDOW_FULLSCREEN | 0x00001000 ),
@@ -112,14 +117,17 @@ typedef enum
112
117
  SDL_WINDOW_ALLOW_HIGHDPI = 0x00002000, /**< window should be created in high-DPI mode if supported.
113
118
  On macOS NSHighResolutionCapable must be set true in the
114
119
  application's Info.plist for this to have any effect. */
115
- SDL_WINDOW_MOUSE_CAPTURE = 0x00004000, /**< window has mouse captured (unrelated to INPUT_GRABBED) */
116
- SDL_WINDOW_ALWAYS_ON_TOP = 0x00008000, /**< window should always be above others */
117
- SDL_WINDOW_SKIP_TASKBAR = 0x00010000, /**< window should not be added to the taskbar */
118
- SDL_WINDOW_UTILITY = 0x00020000, /**< window should be treated as a utility window */
119
- SDL_WINDOW_TOOLTIP = 0x00040000, /**< window should be treated as a tooltip */
120
- SDL_WINDOW_POPUP_MENU = 0x00080000, /**< window should be treated as a popup menu */
121
- SDL_WINDOW_VULKAN = 0x10000000, /**< window usable for Vulkan surface */
122
- SDL_WINDOW_METAL = 0x20000000 /**< window usable for Metal view */
120
+ SDL_WINDOW_MOUSE_CAPTURE = 0x00004000, /**< window has mouse captured (unrelated to MOUSE_GRABBED) */
121
+ SDL_WINDOW_ALWAYS_ON_TOP = 0x00008000, /**< window should always be above others */
122
+ SDL_WINDOW_SKIP_TASKBAR = 0x00010000, /**< window should not be added to the taskbar */
123
+ SDL_WINDOW_UTILITY = 0x00020000, /**< window should be treated as a utility window */
124
+ SDL_WINDOW_TOOLTIP = 0x00040000, /**< window should be treated as a tooltip */
125
+ SDL_WINDOW_POPUP_MENU = 0x00080000, /**< window should be treated as a popup menu */
126
+ SDL_WINDOW_KEYBOARD_GRABBED = 0x00100000, /**< window has grabbed keyboard input */
127
+ SDL_WINDOW_VULKAN = 0x10000000, /**< window usable for Vulkan surface */
128
+ SDL_WINDOW_METAL = 0x20000000, /**< window usable for Metal view */
129
+
130
+ SDL_WINDOW_INPUT_GRABBED = SDL_WINDOW_MOUSE_GRABBED /**< equivalent to SDL_WINDOW_MOUSE_GRABBED for compatibility */
123
131
  } SDL_WindowFlags;
124
132
 
125
133
  /**
@@ -166,7 +174,9 @@ typedef enum
166
174
  SDL_WINDOWEVENT_FOCUS_LOST, /**< Window has lost keyboard focus */
167
175
  SDL_WINDOWEVENT_CLOSE, /**< The window manager requests that the window be closed */
168
176
  SDL_WINDOWEVENT_TAKE_FOCUS, /**< Window is being offered a focus (should SetWindowInputFocus() on itself or a subwindow, or ignore) */
169
- SDL_WINDOWEVENT_HIT_TEST /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL. */
177
+ SDL_WINDOWEVENT_HIT_TEST, /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL. */
178
+ SDL_WINDOWEVENT_ICCPROF_CHANGED,/**< The ICC profile of the window's display has changed. */
179
+ SDL_WINDOWEVENT_DISPLAY_CHANGED /**< Window has been moved to display data1. */
170
180
  } SDL_WindowEventID;
171
181
 
172
182
  /**
@@ -180,6 +190,9 @@ typedef enum
180
190
  SDL_DISPLAYEVENT_DISCONNECTED /**< Display has been removed from the system */
181
191
  } SDL_DisplayEventID;
182
192
 
193
+ /**
194
+ * \brief Display orientation
195
+ */
183
196
  typedef enum
184
197
  {
185
198
  SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */
@@ -189,6 +202,16 @@ typedef enum
189
202
  SDL_ORIENTATION_PORTRAIT_FLIPPED /**< The display is in portrait mode, upside down */
190
203
  } SDL_DisplayOrientation;
191
204
 
205
+ /**
206
+ * \brief Window flash operation
207
+ */
208
+ typedef enum
209
+ {
210
+ SDL_FLASH_CANCEL, /**< Cancel any window flash state */
211
+ SDL_FLASH_BRIEFLY, /**< Flash the window briefly to get attention */
212
+ SDL_FLASH_UNTIL_FOCUSED /**< Flash the window until it gets focus */
213
+ } SDL_FlashOperation;
214
+
192
215
  /**
193
216
  * \brief An opaque handle to an OpenGL context.
194
217
  */
@@ -258,740 +281,1299 @@ typedef enum
258
281
  /* Function prototypes */
259
282
 
260
283
  /**
261
- * \brief Get the number of video drivers compiled into SDL
284
+ * Get the number of video drivers compiled into SDL.
285
+ *
286
+ * \returns a number >= 1 on success or a negative error code on failure; call
287
+ * SDL_GetError() for more information.
288
+ *
289
+ * \since This function is available since SDL 2.0.0.
262
290
  *
263
- * \sa SDL_GetVideoDriver()
291
+ * \sa SDL_GetVideoDriver
264
292
  */
265
293
  extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
266
294
 
267
295
  /**
268
- * \brief Get the name of a built in video driver.
296
+ * Get the name of a built in video driver.
269
297
  *
270
- * \note The video drivers are presented in the order in which they are
271
- * normally checked during initialization.
298
+ * The video drivers are presented in the order in which they are normally
299
+ * checked during initialization.
272
300
  *
273
- * \sa SDL_GetNumVideoDrivers()
301
+ * \param index the index of a video driver
302
+ * \returns the name of the video driver with the given **index**.
303
+ *
304
+ * \since This function is available since SDL 2.0.0.
305
+ *
306
+ * \sa SDL_GetNumVideoDrivers
274
307
  */
275
308
  extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
276
309
 
277
310
  /**
278
- * \brief Initialize the video subsystem, optionally specifying a video driver.
311
+ * Initialize the video subsystem, optionally specifying a video driver.
312
+ *
313
+ * This function initializes the video subsystem, setting up a connection to
314
+ * the window manager, etc, and determines the available display modes and
315
+ * pixel formats, but does not initialize a window or graphics mode.
316
+ *
317
+ * If you use this function and you haven't used the SDL_INIT_VIDEO flag with
318
+ * either SDL_Init() or SDL_InitSubSystem(), you should call SDL_VideoQuit()
319
+ * before calling SDL_Quit().
279
320
  *
280
- * \param driver_name Initialize a specific driver by name, or NULL for the
281
- * default video driver.
321
+ * It is safe to call this function multiple times. SDL_VideoInit() will call
322
+ * SDL_VideoQuit() itself if the video subsystem has already been initialized.
282
323
  *
283
- * \return 0 on success, -1 on error
324
+ * You can use SDL_GetNumVideoDrivers() and SDL_GetVideoDriver() to find a
325
+ * specific `driver_name`.
284
326
  *
285
- * This function initializes the video subsystem; setting up a connection
286
- * to the window manager, etc, and determines the available display modes
287
- * and pixel formats, but does not initialize a window or graphics mode.
327
+ * \param driver_name the name of a video driver to initialize, or NULL for
328
+ * the default driver
329
+ * \returns 0 on success or a negative error code on failure; call
330
+ * SDL_GetError() for more information.
288
331
  *
289
- * \sa SDL_VideoQuit()
332
+ * \since This function is available since SDL 2.0.0.
333
+ *
334
+ * \sa SDL_GetNumVideoDrivers
335
+ * \sa SDL_GetVideoDriver
336
+ * \sa SDL_InitSubSystem
337
+ * \sa SDL_VideoQuit
290
338
  */
291
339
  extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name);
292
340
 
293
341
  /**
294
- * \brief Shuts down the video subsystem.
342
+ * Shut down the video subsystem, if initialized with SDL_VideoInit().
343
+ *
344
+ * This function closes all windows, and restores the original video mode.
295
345
  *
296
- * This function closes all windows, and restores the original video mode.
346
+ * \since This function is available since SDL 2.0.0.
297
347
  *
298
- * \sa SDL_VideoInit()
348
+ * \sa SDL_VideoInit
299
349
  */
300
350
  extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
301
351
 
302
352
  /**
303
- * \brief Returns the name of the currently initialized video driver.
353
+ * Get the name of the currently initialized video driver.
304
354
  *
305
- * \return The name of the current video driver or NULL if no driver
306
- * has been initialized
355
+ * \returns the name of the current video driver or NULL if no driver has been
356
+ * initialized.
307
357
  *
308
- * \sa SDL_GetNumVideoDrivers()
309
- * \sa SDL_GetVideoDriver()
358
+ * \since This function is available since SDL 2.0.0.
359
+ *
360
+ * \sa SDL_GetNumVideoDrivers
361
+ * \sa SDL_GetVideoDriver
310
362
  */
311
363
  extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
312
364
 
313
365
  /**
314
- * \brief Returns the number of available video displays.
366
+ * Get the number of available video displays.
367
+ *
368
+ * \returns a number >= 1 or a negative error code on failure; call
369
+ * SDL_GetError() for more information.
315
370
  *
316
- * \sa SDL_GetDisplayBounds()
371
+ * \since This function is available since SDL 2.0.0.
372
+ *
373
+ * \sa SDL_GetDisplayBounds
317
374
  */
318
375
  extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
319
376
 
320
377
  /**
321
- * \brief Get the name of a display in UTF-8 encoding
378
+ * Get the name of a display in UTF-8 encoding.
379
+ *
380
+ * \param displayIndex the index of display from which the name should be
381
+ * queried
382
+ * \returns the name of a display or NULL for an invalid display index or
383
+ * failure; call SDL_GetError() for more information.
322
384
  *
323
- * \return The name of a display, or NULL for an invalid display index.
385
+ * \since This function is available since SDL 2.0.0.
324
386
  *
325
- * \sa SDL_GetNumVideoDisplays()
387
+ * \sa SDL_GetNumVideoDisplays
326
388
  */
327
389
  extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex);
328
390
 
329
391
  /**
330
- * \brief Get the desktop area represented by a display, with the primary
331
- * display located at 0,0
392
+ * Get the desktop area represented by a display.
393
+ *
394
+ * The primary display (`displayIndex` zero) is always located at 0,0.
332
395
  *
333
- * \return 0 on success, or -1 if the index is out of range.
396
+ * \param displayIndex the index of the display to query
397
+ * \param rect the SDL_Rect structure filled in with the display bounds
398
+ * \returns 0 on success or a negative error code on failure; call
399
+ * SDL_GetError() for more information.
334
400
  *
335
- * \sa SDL_GetNumVideoDisplays()
401
+ * \since This function is available since SDL 2.0.0.
402
+ *
403
+ * \sa SDL_GetNumVideoDisplays
336
404
  */
337
405
  extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * rect);
338
406
 
339
407
  /**
340
- * \brief Get the usable desktop area represented by a display, with the
341
- * primary display located at 0,0
408
+ * Get the usable desktop area represented by a display.
409
+ *
410
+ * The primary display (`displayIndex` zero) is always located at 0,0.
342
411
  *
343
- * This is the same area as SDL_GetDisplayBounds() reports, but with portions
344
- * reserved by the system removed. For example, on Mac OS X, this subtracts
345
- * the area occupied by the menu bar and dock.
412
+ * This is the same area as SDL_GetDisplayBounds() reports, but with portions
413
+ * reserved by the system removed. For example, on Apple's macOS, this
414
+ * subtracts the area occupied by the menu bar and dock.
346
415
  *
347
- * Setting a window to be fullscreen generally bypasses these unusable areas,
348
- * so these are good guidelines for the maximum space available to a
349
- * non-fullscreen window.
416
+ * Setting a window to be fullscreen generally bypasses these unusable areas,
417
+ * so these are good guidelines for the maximum space available to a
418
+ * non-fullscreen window.
350
419
  *
351
- * \return 0 on success, or -1 if the index is out of range.
420
+ * The parameter `rect` is ignored if it is NULL.
352
421
  *
353
- * \sa SDL_GetDisplayBounds()
354
- * \sa SDL_GetNumVideoDisplays()
422
+ * This function also returns -1 if the parameter `displayIndex` is out of
423
+ * range.
424
+ *
425
+ * \param displayIndex the index of the display to query the usable bounds
426
+ * from
427
+ * \param rect the SDL_Rect structure filled in with the display bounds
428
+ * \returns 0 on success or a negative error code on failure; call
429
+ * SDL_GetError() for more information.
430
+ *
431
+ * \since This function is available since SDL 2.0.5.
432
+ *
433
+ * \sa SDL_GetDisplayBounds
434
+ * \sa SDL_GetNumVideoDisplays
355
435
  */
356
436
  extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rect * rect);
357
437
 
358
438
  /**
359
- * \brief Get the dots/pixels-per-inch for a display
439
+ * Get the dots/pixels-per-inch for a display.
440
+ *
441
+ * Diagonal, horizontal and vertical DPI can all be optionally returned if the
442
+ * appropriate parameter is non-NULL.
360
443
  *
361
- * \note Diagonal, horizontal and vertical DPI can all be optionally
362
- * returned if the parameter is non-NULL.
444
+ * A failure of this function usually means that either no DPI information is
445
+ * available or the `displayIndex` is out of range.
363
446
  *
364
- * \return 0 on success, or -1 if no DPI information is available or the index is out of range.
447
+ * \param displayIndex the index of the display from which DPI information
448
+ * should be queried
449
+ * \param ddpi a pointer filled in with the diagonal DPI of the display; may
450
+ * be NULL
451
+ * \param hdpi a pointer filled in with the horizontal DPI of the display; may
452
+ * be NULL
453
+ * \param vdpi a pointer filled in with the vertical DPI of the display; may
454
+ * be NULL
455
+ * \returns 0 on success or a negative error code on failure; call
456
+ * SDL_GetError() for more information.
365
457
  *
366
- * \sa SDL_GetNumVideoDisplays()
458
+ * \since This function is available since SDL 2.0.4.
459
+ *
460
+ * \sa SDL_GetNumVideoDisplays
367
461
  */
368
462
  extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, float * hdpi, float * vdpi);
369
463
 
370
464
  /**
371
- * \brief Get the orientation of a display
465
+ * Get the orientation of a display.
466
+ *
467
+ * \param displayIndex the index of the display to query
468
+ * \returns The SDL_DisplayOrientation enum value of the display, or
469
+ * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
372
470
  *
373
- * \return The orientation of the display, or SDL_ORIENTATION_UNKNOWN if it isn't available.
471
+ * \since This function is available since SDL 2.0.9.
374
472
  *
375
- * \sa SDL_GetNumVideoDisplays()
473
+ * \sa SDL_GetNumVideoDisplays
376
474
  */
377
475
  extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex);
378
476
 
379
477
  /**
380
- * \brief Returns the number of available display modes.
478
+ * Get the number of available display modes.
381
479
  *
382
- * \sa SDL_GetDisplayMode()
480
+ * The `displayIndex` needs to be in the range from 0 to
481
+ * SDL_GetNumVideoDisplays() - 1.
482
+ *
483
+ * \param displayIndex the index of the display to query
484
+ * \returns a number >= 1 on success or a negative error code on failure; call
485
+ * SDL_GetError() for more information.
486
+ *
487
+ * \since This function is available since SDL 2.0.0.
488
+ *
489
+ * \sa SDL_GetDisplayMode
490
+ * \sa SDL_GetNumVideoDisplays
383
491
  */
384
492
  extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex);
385
493
 
386
494
  /**
387
- * \brief Fill in information about a specific display mode.
495
+ * Get information about a specific display mode.
388
496
  *
389
- * \note The display modes are sorted in this priority:
390
- * \li bits per pixel -> more colors to fewer colors
391
- * \li width -> largest to smallest
392
- * \li height -> largest to smallest
393
- * \li refresh rate -> highest to lowest
497
+ * The display modes are sorted in this priority:
394
498
  *
395
- * \sa SDL_GetNumDisplayModes()
499
+ * - width -> largest to smallest
500
+ * - height -> largest to smallest
501
+ * - bits per pixel -> more colors to fewer colors
502
+ * - packed pixel layout -> largest to smallest
503
+ * - refresh rate -> highest to lowest
504
+ *
505
+ * \param displayIndex the index of the display to query
506
+ * \param modeIndex the index of the display mode to query
507
+ * \param mode an SDL_DisplayMode structure filled in with the mode at
508
+ * `modeIndex`
509
+ * \returns 0 on success or a negative error code on failure; call
510
+ * SDL_GetError() for more information.
511
+ *
512
+ * \since This function is available since SDL 2.0.0.
513
+ *
514
+ * \sa SDL_GetNumDisplayModes
396
515
  */
397
516
  extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex,
398
517
  SDL_DisplayMode * mode);
399
518
 
400
519
  /**
401
- * \brief Fill in information about the desktop display mode.
520
+ * Get information about the desktop's display mode.
521
+ *
522
+ * There's a difference between this function and SDL_GetCurrentDisplayMode()
523
+ * when SDL runs fullscreen and has changed the resolution. In that case this
524
+ * function will return the previous native display mode, and not the current
525
+ * display mode.
526
+ *
527
+ * \param displayIndex the index of the display to query
528
+ * \param mode an SDL_DisplayMode structure filled in with the current display
529
+ * mode
530
+ * \returns 0 on success or a negative error code on failure; call
531
+ * SDL_GetError() for more information.
532
+ *
533
+ * \since This function is available since SDL 2.0.0.
534
+ *
535
+ * \sa SDL_GetCurrentDisplayMode
536
+ * \sa SDL_GetDisplayMode
537
+ * \sa SDL_SetWindowDisplayMode
402
538
  */
403
539
  extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_DisplayMode * mode);
404
540
 
405
541
  /**
406
- * \brief Fill in information about the current display mode.
542
+ * Get information about the current display mode.
543
+ *
544
+ * There's a difference between this function and SDL_GetDesktopDisplayMode()
545
+ * when SDL runs fullscreen and has changed the resolution. In that case this
546
+ * function will return the current display mode, and not the previous native
547
+ * display mode.
548
+ *
549
+ * \param displayIndex the index of the display to query
550
+ * \param mode an SDL_DisplayMode structure filled in with the current display
551
+ * mode
552
+ * \returns 0 on success or a negative error code on failure; call
553
+ * SDL_GetError() for more information.
554
+ *
555
+ * \since This function is available since SDL 2.0.0.
556
+ *
557
+ * \sa SDL_GetDesktopDisplayMode
558
+ * \sa SDL_GetDisplayMode
559
+ * \sa SDL_GetNumVideoDisplays
560
+ * \sa SDL_SetWindowDisplayMode
407
561
  */
408
562
  extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode * mode);
409
563
 
410
564
 
411
565
  /**
412
- * \brief Get the closest match to the requested display mode.
566
+ * Get the closest match to the requested display mode.
413
567
  *
414
- * \param displayIndex The index of display from which mode should be queried.
415
- * \param mode The desired display mode
416
- * \param closest A pointer to a display mode to be filled in with the closest
417
- * match of the available display modes.
568
+ * The available display modes are scanned and `closest` is filled in with the
569
+ * closest mode matching the requested mode and returned. The mode format and
570
+ * refresh rate default to the desktop mode if they are set to 0. The modes
571
+ * are scanned with size being first priority, format being second priority,
572
+ * and finally checking the refresh rate. If all the available modes are too
573
+ * small, then NULL is returned.
418
574
  *
419
- * \return The passed in value \c closest, or NULL if no matching video mode
420
- * was available.
575
+ * \param displayIndex the index of the display to query
576
+ * \param mode an SDL_DisplayMode structure containing the desired display
577
+ * mode
578
+ * \param closest an SDL_DisplayMode structure filled in with the closest
579
+ * match of the available display modes
580
+ * \returns the passed in value `closest` or NULL if no matching video mode
581
+ * was available; call SDL_GetError() for more information.
421
582
  *
422
- * The available display modes are scanned, and \c closest is filled in with the
423
- * closest mode matching the requested mode and returned. The mode format and
424
- * refresh_rate default to the desktop mode if they are 0. The modes are
425
- * scanned with size being first priority, format being second priority, and
426
- * finally checking the refresh_rate. If all the available modes are too
427
- * small, then NULL is returned.
583
+ * \since This function is available since SDL 2.0.0.
428
584
  *
429
- * \sa SDL_GetNumDisplayModes()
430
- * \sa SDL_GetDisplayMode()
585
+ * \sa SDL_GetDisplayMode
586
+ * \sa SDL_GetNumDisplayModes
431
587
  */
432
588
  extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest);
433
589
 
434
590
  /**
435
- * \brief Get the display index associated with a window.
591
+ * Get the index of the display associated with a window.
592
+ *
593
+ * \param window the window to query
594
+ * \returns the index of the display containing the center of the window on
595
+ * success or a negative error code on failure; call SDL_GetError()
596
+ * for more information.
436
597
  *
437
- * \return the display index of the display containing the center of the
438
- * window, or -1 on error.
598
+ * \since This function is available since SDL 2.0.0.
599
+ *
600
+ * \sa SDL_GetDisplayBounds
601
+ * \sa SDL_GetNumVideoDisplays
439
602
  */
440
603
  extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window);
441
604
 
442
605
  /**
443
- * \brief Set the display mode used when a fullscreen window is visible.
606
+ * Set the display mode to use when a window is visible at fullscreen.
444
607
  *
445
- * By default the window's dimensions and the desktop format and refresh rate
446
- * are used.
608
+ * This only affects the display mode used when the window is fullscreen. To
609
+ * change the window size when the window is not fullscreen, use
610
+ * SDL_SetWindowSize().
447
611
  *
448
- * \param window The window for which the display mode should be set.
449
- * \param mode The mode to use, or NULL for the default mode.
612
+ * \param window the window to affect
613
+ * \param mode the SDL_DisplayMode structure representing the mode to use, or
614
+ * NULL to use the window's dimensions and the desktop's format
615
+ * and refresh rate
616
+ * \returns 0 on success or a negative error code on failure; call
617
+ * SDL_GetError() for more information.
450
618
  *
451
- * \return 0 on success, or -1 if setting the display mode failed.
619
+ * \since This function is available since SDL 2.0.0.
452
620
  *
453
- * \sa SDL_GetWindowDisplayMode()
454
- * \sa SDL_SetWindowFullscreen()
621
+ * \sa SDL_GetWindowDisplayMode
622
+ * \sa SDL_SetWindowFullscreen
455
623
  */
456
624
  extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window,
457
- const SDL_DisplayMode
458
- * mode);
625
+ const SDL_DisplayMode * mode);
459
626
 
460
627
  /**
461
- * \brief Fill in information about the display mode used when a fullscreen
462
- * window is visible.
628
+ * Query the display mode to use when a window is visible at fullscreen.
463
629
  *
464
- * \sa SDL_SetWindowDisplayMode()
465
- * \sa SDL_SetWindowFullscreen()
630
+ * \param window the window to query
631
+ * \param mode an SDL_DisplayMode structure filled in with the fullscreen
632
+ * display mode
633
+ * \returns 0 on success or a negative error code on failure; call
634
+ * SDL_GetError() for more information.
635
+ *
636
+ * \since This function is available since SDL 2.0.0.
637
+ *
638
+ * \sa SDL_SetWindowDisplayMode
639
+ * \sa SDL_SetWindowFullscreen
466
640
  */
467
641
  extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window,
468
642
  SDL_DisplayMode * mode);
469
643
 
470
644
  /**
471
- * \brief Get the pixel format associated with the window.
472
- */
473
- extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
474
-
475
- /**
476
- * \brief Create a window with the specified position, dimensions, and flags.
477
- *
478
- * \param title The title of the window, in UTF-8 encoding.
479
- * \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
480
- * ::SDL_WINDOWPOS_UNDEFINED.
481
- * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
482
- * ::SDL_WINDOWPOS_UNDEFINED.
483
- * \param w The width of the window, in screen coordinates.
484
- * \param h The height of the window, in screen coordinates.
485
- * \param flags The flags for the window, a mask of any of the following:
486
- * ::SDL_WINDOW_FULLSCREEN, ::SDL_WINDOW_OPENGL,
487
- * ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_BORDERLESS,
488
- * ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
489
- * ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_INPUT_GRABBED,
490
- * ::SDL_WINDOW_ALLOW_HIGHDPI, ::SDL_WINDOW_VULKAN
491
- * ::SDL_WINDOW_METAL.
492
- *
493
- * \return The created window, or NULL if window creation failed.
645
+ * Get the raw ICC profile data for the screen the window is currently on.
494
646
  *
495
- * If the window is created with the SDL_WINDOW_ALLOW_HIGHDPI flag, its size
496
- * in pixels may differ from its size in screen coordinates on platforms with
497
- * high-DPI support (e.g. iOS and Mac OS X). Use SDL_GetWindowSize() to query
498
- * the client area's size in screen coordinates, and SDL_GL_GetDrawableSize(),
499
- * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to query the
500
- * drawable size in pixels.
647
+ * Data returned should be freed with SDL_free.
501
648
  *
502
- * If the window is created with any of the SDL_WINDOW_OPENGL or
503
- * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
504
- * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
505
- * corresponding UnloadLibrary function is called by SDL_DestroyWindow().
649
+ * \param window the window to query
650
+ * \param size the size of the ICC profile
651
+ * \returns the raw ICC profile data on success or NULL on failure; call
652
+ * SDL_GetError() for more information.
506
653
  *
507
- * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver,
508
- * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail.
509
- *
510
- * If SDL_WINDOW_METAL is specified on an OS that does not support Metal,
511
- * SDL_CreateWindow() will fail.
654
+ * \since This function is available since SDL 2.0.18.
655
+ */
656
+ extern DECLSPEC void* SDLCALL SDL_GetWindowICCProfile(SDL_Window * window, size_t* size);
657
+
658
+ /**
659
+ * Get the pixel format associated with the window.
512
660
  *
513
- * \note On non-Apple devices, SDL requires you to either not link to the
514
- * Vulkan loader or link to a dynamic library version. This limitation
515
- * may be removed in a future version of SDL.
661
+ * \param window the window to query
662
+ * \returns the pixel format of the window on success or
663
+ * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more
664
+ * information.
516
665
  *
517
- * \sa SDL_DestroyWindow()
518
- * \sa SDL_GL_LoadLibrary()
519
- * \sa SDL_Vulkan_LoadLibrary()
666
+ * \since This function is available since SDL 2.0.0.
667
+ */
668
+ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
669
+
670
+ /**
671
+ * Create a window with the specified position, dimensions, and flags.
672
+ *
673
+ * `flags` may be any of the following OR'd together:
674
+ *
675
+ * - `SDL_WINDOW_FULLSCREEN`: fullscreen window
676
+ * - `SDL_WINDOW_FULLSCREEN_DESKTOP`: fullscreen window at desktop resolution
677
+ * - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context
678
+ * - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance
679
+ * - `SDL_WINDOW_METAL`: window usable with a Metal instance
680
+ * - `SDL_WINDOW_HIDDEN`: window is not visible
681
+ * - `SDL_WINDOW_BORDERLESS`: no window decoration
682
+ * - `SDL_WINDOW_RESIZABLE`: window can be resized
683
+ * - `SDL_WINDOW_MINIMIZED`: window is minimized
684
+ * - `SDL_WINDOW_MAXIMIZED`: window is maximized
685
+ * - `SDL_WINDOW_INPUT_GRABBED`: window has grabbed input focus
686
+ * - `SDL_WINDOW_ALLOW_HIGHDPI`: window should be created in high-DPI mode if
687
+ * supported (>= SDL 2.0.1)
688
+ *
689
+ * `SDL_WINDOW_SHOWN` is ignored by SDL_CreateWindow(). The SDL_Window is
690
+ * implicitly shown if SDL_WINDOW_HIDDEN is not set. `SDL_WINDOW_SHOWN` may be
691
+ * queried later using SDL_GetWindowFlags().
692
+ *
693
+ * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
694
+ * property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
695
+ *
696
+ * If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size
697
+ * in pixels may differ from its size in screen coordinates on platforms with
698
+ * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query the
699
+ * client area's size in screen coordinates, and SDL_GL_GetDrawableSize() or
700
+ * SDL_GetRendererOutputSize() to query the drawable size in pixels.
701
+ *
702
+ * If the window is set fullscreen, the width and height parameters `w` and
703
+ * `h` will not be used. However, invalid size parameters (e.g. too large) may
704
+ * still fail. Window size is actually limited to 16384 x 16384 for all
705
+ * platforms at window creation.
706
+ *
707
+ * If the window is created with any of the SDL_WINDOW_OPENGL or
708
+ * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
709
+ * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
710
+ * corresponding UnloadLibrary function is called by SDL_DestroyWindow().
711
+ *
712
+ * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver,
713
+ * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail.
714
+ *
715
+ * If SDL_WINDOW_METAL is specified on an OS that does not support Metal,
716
+ * SDL_CreateWindow() will fail.
717
+ *
718
+ * On non-Apple devices, SDL requires you to either not link to the Vulkan
719
+ * loader or link to a dynamic library version. This limitation may be removed
720
+ * in a future version of SDL.
721
+ *
722
+ * \param title the title of the window, in UTF-8 encoding
723
+ * \param x the x position of the window, `SDL_WINDOWPOS_CENTERED`, or
724
+ * `SDL_WINDOWPOS_UNDEFINED`
725
+ * \param y the y position of the window, `SDL_WINDOWPOS_CENTERED`, or
726
+ * `SDL_WINDOWPOS_UNDEFINED`
727
+ * \param w the width of the window, in screen coordinates
728
+ * \param h the height of the window, in screen coordinates
729
+ * \param flags 0, or one or more SDL_WindowFlags OR'd together
730
+ * \returns the window that was created or NULL on failure; call
731
+ * SDL_GetError() for more information.
732
+ *
733
+ * \since This function is available since SDL 2.0.0.
734
+ *
735
+ * \sa SDL_CreateWindowFrom
736
+ * \sa SDL_DestroyWindow
520
737
  */
521
738
  extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title,
522
739
  int x, int y, int w,
523
740
  int h, Uint32 flags);
524
741
 
525
742
  /**
526
- * \brief Create an SDL window from an existing native window.
743
+ * Create an SDL window from an existing native window.
527
744
  *
528
- * \param data A pointer to driver-dependent window creation data
745
+ * In some cases (e.g. OpenGL) and on some platforms (e.g. Microsoft Windows)
746
+ * the hint `SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT` needs to be configured
747
+ * before using SDL_CreateWindowFrom().
529
748
  *
530
- * \return The created window, or NULL if window creation failed.
749
+ * \param data a pointer to driver-dependent window creation data, typically
750
+ * your native window cast to a void*
751
+ * \returns the window that was created or NULL on failure; call
752
+ * SDL_GetError() for more information.
531
753
  *
532
- * \sa SDL_DestroyWindow()
754
+ * \since This function is available since SDL 2.0.0.
755
+ *
756
+ * \sa SDL_CreateWindow
757
+ * \sa SDL_DestroyWindow
533
758
  */
534
759
  extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data);
535
760
 
536
761
  /**
537
- * \brief Get the numeric ID of a window, for logging purposes.
762
+ * Get the numeric ID of a window.
763
+ *
764
+ * The numeric ID is what SDL_WindowEvent references, and is necessary to map
765
+ * these events to specific SDL_Window objects.
766
+ *
767
+ * \param window the window to query
768
+ * \returns the ID of the window on success or 0 on failure; call
769
+ * SDL_GetError() for more information.
770
+ *
771
+ * \since This function is available since SDL 2.0.0.
772
+ *
773
+ * \sa SDL_GetWindowFromID
538
774
  */
539
775
  extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window);
540
776
 
541
777
  /**
542
- * \brief Get a window from a stored ID, or NULL if it doesn't exist.
778
+ * Get a window from a stored ID.
779
+ *
780
+ * The numeric ID is what SDL_WindowEvent references, and is necessary to map
781
+ * these events to specific SDL_Window objects.
782
+ *
783
+ * \param id the ID of the window
784
+ * \returns the window associated with `id` or NULL if it doesn't exist; call
785
+ * SDL_GetError() for more information.
786
+ *
787
+ * \since This function is available since SDL 2.0.0.
788
+ *
789
+ * \sa SDL_GetWindowID
543
790
  */
544
791
  extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id);
545
792
 
546
793
  /**
547
- * \brief Get the window flags.
794
+ * Get the window flags.
795
+ *
796
+ * \param window the window to query
797
+ * \returns a mask of the SDL_WindowFlags associated with `window`
798
+ *
799
+ * \since This function is available since SDL 2.0.0.
800
+ *
801
+ * \sa SDL_CreateWindow
802
+ * \sa SDL_HideWindow
803
+ * \sa SDL_MaximizeWindow
804
+ * \sa SDL_MinimizeWindow
805
+ * \sa SDL_SetWindowFullscreen
806
+ * \sa SDL_SetWindowGrab
807
+ * \sa SDL_ShowWindow
548
808
  */
549
809
  extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window);
550
810
 
551
811
  /**
552
- * \brief Set the title of a window, in UTF-8 format.
812
+ * Set the title of a window.
553
813
  *
554
- * \sa SDL_GetWindowTitle()
814
+ * This string is expected to be in UTF-8 encoding.
815
+ *
816
+ * \param window the window to change
817
+ * \param title the desired window title in UTF-8 format
818
+ *
819
+ * \since This function is available since SDL 2.0.0.
820
+ *
821
+ * \sa SDL_GetWindowTitle
555
822
  */
556
823
  extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window,
557
824
  const char *title);
558
825
 
559
826
  /**
560
- * \brief Get the title of a window, in UTF-8 format.
827
+ * Get the title of a window.
561
828
  *
562
- * \sa SDL_SetWindowTitle()
829
+ * \param window the window to query
830
+ * \returns the title of the window in UTF-8 format or "" if there is no
831
+ * title.
832
+ *
833
+ * \since This function is available since SDL 2.0.0.
834
+ *
835
+ * \sa SDL_SetWindowTitle
563
836
  */
564
837
  extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window);
565
838
 
566
839
  /**
567
- * \brief Set the icon for a window.
840
+ * Set the icon for a window.
841
+ *
842
+ * \param window the window to change
843
+ * \param icon an SDL_Surface structure containing the icon for the window
568
844
  *
569
- * \param window The window for which the icon should be set.
570
- * \param icon The icon for the window.
845
+ * \since This function is available since SDL 2.0.0.
571
846
  */
572
847
  extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window,
573
848
  SDL_Surface * icon);
574
849
 
575
850
  /**
576
- * \brief Associate an arbitrary named pointer with a window.
851
+ * Associate an arbitrary named pointer with a window.
577
852
  *
578
- * \param window The window to associate with the pointer.
579
- * \param name The name of the pointer.
580
- * \param userdata The associated pointer.
853
+ * `name` is case-sensitive.
581
854
  *
582
- * \return The previous value associated with 'name'
855
+ * \param window the window to associate with the pointer
856
+ * \param name the name of the pointer
857
+ * \param userdata the associated pointer
858
+ * \returns the previous value associated with `name`.
583
859
  *
584
- * \note The name is case-sensitive.
860
+ * \since This function is available since SDL 2.0.0.
585
861
  *
586
- * \sa SDL_GetWindowData()
862
+ * \sa SDL_GetWindowData
587
863
  */
588
864
  extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window,
589
865
  const char *name,
590
866
  void *userdata);
591
867
 
592
868
  /**
593
- * \brief Retrieve the data pointer associated with a window.
869
+ * Retrieve the data pointer associated with a window.
594
870
  *
595
- * \param window The window to query.
596
- * \param name The name of the pointer.
871
+ * \param window the window to query
872
+ * \param name the name of the pointer
873
+ * \returns the value associated with `name`.
597
874
  *
598
- * \return The value associated with 'name'
875
+ * \since This function is available since SDL 2.0.0.
599
876
  *
600
- * \sa SDL_SetWindowData()
877
+ * \sa SDL_SetWindowData
601
878
  */
602
879
  extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window,
603
880
  const char *name);
604
881
 
605
882
  /**
606
- * \brief Set the position of a window.
883
+ * Set the position of a window.
607
884
  *
608
- * \param window The window to reposition.
609
- * \param x The x coordinate of the window in screen coordinates, or
610
- * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
611
- * \param y The y coordinate of the window in screen coordinates, or
612
- * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
885
+ * The window coordinate origin is the upper left of the display.
613
886
  *
614
- * \note The window coordinate origin is the upper left of the display.
887
+ * \param window the window to reposition
888
+ * \param x the x coordinate of the window in screen coordinates, or
889
+ * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
890
+ * \param y the y coordinate of the window in screen coordinates, or
891
+ * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
615
892
  *
616
- * \sa SDL_GetWindowPosition()
893
+ * \since This function is available since SDL 2.0.0.
894
+ *
895
+ * \sa SDL_GetWindowPosition
617
896
  */
618
897
  extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window,
619
898
  int x, int y);
620
899
 
621
900
  /**
622
- * \brief Get the position of a window.
901
+ * Get the position of a window.
623
902
  *
624
- * \param window The window to query.
625
- * \param x Pointer to variable for storing the x position, in screen
626
- * coordinates. May be NULL.
627
- * \param y Pointer to variable for storing the y position, in screen
628
- * coordinates. May be NULL.
903
+ * If you do not need the value for one of the positions a NULL may be passed
904
+ * in the `x` or `y` parameter.
629
905
  *
630
- * \sa SDL_SetWindowPosition()
906
+ * \param window the window to query
907
+ * \param x a pointer filled in with the x position of the window, in screen
908
+ * coordinates, may be NULL
909
+ * \param y a pointer filled in with the y position of the window, in screen
910
+ * coordinates, may be NULL
911
+ *
912
+ * \since This function is available since SDL 2.0.0.
913
+ *
914
+ * \sa SDL_SetWindowPosition
631
915
  */
632
916
  extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window,
633
917
  int *x, int *y);
634
918
 
635
919
  /**
636
- * \brief Set the size of a window's client area.
920
+ * Set the size of a window's client area.
637
921
  *
638
- * \param window The window to resize.
639
- * \param w The width of the window, in screen coordinates. Must be >0.
640
- * \param h The height of the window, in screen coordinates. Must be >0.
922
+ * The window size in screen coordinates may differ from the size in pixels,
923
+ * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform
924
+ * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize() or
925
+ * SDL_GetRendererOutputSize() to get the real client area size in pixels.
641
926
  *
642
- * \note Fullscreen windows automatically match the size of the display mode,
643
- * and you should use SDL_SetWindowDisplayMode() to change their size.
927
+ * Fullscreen windows automatically match the size of the display mode, and
928
+ * you should use SDL_SetWindowDisplayMode() to change their size.
644
929
  *
645
- * The window size in screen coordinates may differ from the size in pixels, if
646
- * the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
647
- * high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or
648
- * SDL_GetRendererOutputSize() to get the real client area size in pixels.
930
+ * \param window the window to change
931
+ * \param w the width of the window in pixels, in screen coordinates, must be
932
+ * > 0
933
+ * \param h the height of the window in pixels, in screen coordinates, must be
934
+ * > 0
649
935
  *
650
- * \sa SDL_GetWindowSize()
651
- * \sa SDL_SetWindowDisplayMode()
936
+ * \since This function is available since SDL 2.0.0.
937
+ *
938
+ * \sa SDL_GetWindowSize
939
+ * \sa SDL_SetWindowDisplayMode
652
940
  */
653
941
  extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w,
654
942
  int h);
655
943
 
656
944
  /**
657
- * \brief Get the size of a window's client area.
945
+ * Get the size of a window's client area.
658
946
  *
659
- * \param window The window to query.
660
- * \param w Pointer to variable for storing the width, in screen
661
- * coordinates. May be NULL.
662
- * \param h Pointer to variable for storing the height, in screen
663
- * coordinates. May be NULL.
947
+ * NULL can safely be passed as the `w` or `h` parameter if the width or
948
+ * height value is not desired.
664
949
  *
665
- * The window size in screen coordinates may differ from the size in pixels, if
666
- * the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
667
- * high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or
668
- * SDL_GetRendererOutputSize() to get the real client area size in pixels.
950
+ * The window size in screen coordinates may differ from the size in pixels,
951
+ * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform
952
+ * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize(),
953
+ * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to get the
954
+ * real client area size in pixels.
669
955
  *
670
- * \sa SDL_SetWindowSize()
956
+ * \param window the window to query the width and height from
957
+ * \param w a pointer filled in with the width of the window, in screen
958
+ * coordinates, may be NULL
959
+ * \param h a pointer filled in with the height of the window, in screen
960
+ * coordinates, may be NULL
961
+ *
962
+ * \since This function is available since SDL 2.0.0.
963
+ *
964
+ * \sa SDL_GL_GetDrawableSize
965
+ * \sa SDL_Vulkan_GetDrawableSize
966
+ * \sa SDL_SetWindowSize
671
967
  */
672
968
  extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w,
673
969
  int *h);
674
970
 
675
971
  /**
676
- * \brief Get the size of a window's borders (decorations) around the client area.
972
+ * Get the size of a window's borders (decorations) around the client area.
973
+ *
974
+ * Note: If this function fails (returns -1), the size values will be
975
+ * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the
976
+ * window in question was borderless.
977
+ *
978
+ * Note: This function may fail on systems where the window has not yet been
979
+ * decorated by the display server (for example, immediately after calling
980
+ * SDL_CreateWindow). It is recommended that you wait at least until the
981
+ * window has been presented and composited, so that the window system has a
982
+ * chance to decorate the window and provide the border dimensions to SDL.
677
983
  *
678
- * \param window The window to query.
679
- * \param top Pointer to variable for storing the size of the top border. NULL is permitted.
680
- * \param left Pointer to variable for storing the size of the left border. NULL is permitted.
681
- * \param bottom Pointer to variable for storing the size of the bottom border. NULL is permitted.
682
- * \param right Pointer to variable for storing the size of the right border. NULL is permitted.
984
+ * This function also returns -1 if getting the information is not supported.
683
985
  *
684
- * \return 0 on success, or -1 if getting this information is not supported.
986
+ * \param window the window to query the size values of the border
987
+ * (decorations) from
988
+ * \param top pointer to variable for storing the size of the top border; NULL
989
+ * is permitted
990
+ * \param left pointer to variable for storing the size of the left border;
991
+ * NULL is permitted
992
+ * \param bottom pointer to variable for storing the size of the bottom
993
+ * border; NULL is permitted
994
+ * \param right pointer to variable for storing the size of the right border;
995
+ * NULL is permitted
996
+ * \returns 0 on success or a negative error code on failure; call
997
+ * SDL_GetError() for more information.
685
998
  *
686
- * \note if this function fails (returns -1), the size values will be
687
- * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as
688
- * if the window in question was borderless.
999
+ * \since This function is available since SDL 2.0.5.
1000
+ *
1001
+ * \sa SDL_GetWindowSize
689
1002
  */
690
1003
  extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window,
691
1004
  int *top, int *left,
692
1005
  int *bottom, int *right);
693
1006
 
694
1007
  /**
695
- * \brief Set the minimum size of a window's client area.
1008
+ * Set the minimum size of a window's client area.
696
1009
  *
697
- * \param window The window to set a new minimum size.
698
- * \param min_w The minimum width of the window, must be >0
699
- * \param min_h The minimum height of the window, must be >0
1010
+ * \param window the window to change
1011
+ * \param min_w the minimum width of the window in pixels
1012
+ * \param min_h the minimum height of the window in pixels
700
1013
  *
701
- * \note You can't change the minimum size of a fullscreen window, it
702
- * automatically matches the size of the display mode.
1014
+ * \since This function is available since SDL 2.0.0.
703
1015
  *
704
- * \sa SDL_GetWindowMinimumSize()
705
- * \sa SDL_SetWindowMaximumSize()
1016
+ * \sa SDL_GetWindowMinimumSize
1017
+ * \sa SDL_SetWindowMaximumSize
706
1018
  */
707
1019
  extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window,
708
1020
  int min_w, int min_h);
709
1021
 
710
1022
  /**
711
- * \brief Get the minimum size of a window's client area.
1023
+ * Get the minimum size of a window's client area.
1024
+ *
1025
+ * \param window the window to query
1026
+ * \param w a pointer filled in with the minimum width of the window, may be
1027
+ * NULL
1028
+ * \param h a pointer filled in with the minimum height of the window, may be
1029
+ * NULL
712
1030
  *
713
- * \param window The window to query.
714
- * \param w Pointer to variable for storing the minimum width, may be NULL
715
- * \param h Pointer to variable for storing the minimum height, may be NULL
1031
+ * \since This function is available since SDL 2.0.0.
716
1032
  *
717
- * \sa SDL_GetWindowMaximumSize()
718
- * \sa SDL_SetWindowMinimumSize()
1033
+ * \sa SDL_GetWindowMaximumSize
1034
+ * \sa SDL_SetWindowMinimumSize
719
1035
  */
720
1036
  extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window,
721
1037
  int *w, int *h);
722
1038
 
723
1039
  /**
724
- * \brief Set the maximum size of a window's client area.
1040
+ * Set the maximum size of a window's client area.
725
1041
  *
726
- * \param window The window to set a new maximum size.
727
- * \param max_w The maximum width of the window, must be >0
728
- * \param max_h The maximum height of the window, must be >0
1042
+ * \param window the window to change
1043
+ * \param max_w the maximum width of the window in pixels
1044
+ * \param max_h the maximum height of the window in pixels
729
1045
  *
730
- * \note You can't change the maximum size of a fullscreen window, it
731
- * automatically matches the size of the display mode.
1046
+ * \since This function is available since SDL 2.0.0.
732
1047
  *
733
- * \sa SDL_GetWindowMaximumSize()
734
- * \sa SDL_SetWindowMinimumSize()
1048
+ * \sa SDL_GetWindowMaximumSize
1049
+ * \sa SDL_SetWindowMinimumSize
735
1050
  */
736
1051
  extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window,
737
1052
  int max_w, int max_h);
738
1053
 
739
1054
  /**
740
- * \brief Get the maximum size of a window's client area.
1055
+ * Get the maximum size of a window's client area.
741
1056
  *
742
- * \param window The window to query.
743
- * \param w Pointer to variable for storing the maximum width, may be NULL
744
- * \param h Pointer to variable for storing the maximum height, may be NULL
1057
+ * \param window the window to query
1058
+ * \param w a pointer filled in with the maximum width of the window, may be
1059
+ * NULL
1060
+ * \param h a pointer filled in with the maximum height of the window, may be
1061
+ * NULL
745
1062
  *
746
- * \sa SDL_GetWindowMinimumSize()
747
- * \sa SDL_SetWindowMaximumSize()
1063
+ * \since This function is available since SDL 2.0.0.
1064
+ *
1065
+ * \sa SDL_GetWindowMinimumSize
1066
+ * \sa SDL_SetWindowMaximumSize
748
1067
  */
749
1068
  extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window,
750
1069
  int *w, int *h);
751
1070
 
752
1071
  /**
753
- * \brief Set the border state of a window.
1072
+ * Set the border state of a window.
754
1073
  *
755
- * This will add or remove the window's SDL_WINDOW_BORDERLESS flag and
756
- * add or remove the border from the actual window. This is a no-op if the
757
- * window's border already matches the requested state.
1074
+ * This will add or remove the window's `SDL_WINDOW_BORDERLESS` flag and add
1075
+ * or remove the border from the actual window. This is a no-op if the
1076
+ * window's border already matches the requested state.
758
1077
  *
759
- * \param window The window of which to change the border state.
760
- * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border.
1078
+ * You can't change the border state of a fullscreen window.
761
1079
  *
762
- * \note You can't change the border state of a fullscreen window.
1080
+ * \param window the window of which to change the border state
1081
+ * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border
763
1082
  *
764
- * \sa SDL_GetWindowFlags()
1083
+ * \since This function is available since SDL 2.0.0.
1084
+ *
1085
+ * \sa SDL_GetWindowFlags
765
1086
  */
766
1087
  extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window,
767
1088
  SDL_bool bordered);
768
1089
 
769
1090
  /**
770
- * \brief Set the user-resizable state of a window.
1091
+ * Set the user-resizable state of a window.
771
1092
  *
772
- * This will add or remove the window's SDL_WINDOW_RESIZABLE flag and
773
- * allow/disallow user resizing of the window. This is a no-op if the
774
- * window's resizable state already matches the requested state.
1093
+ * This will add or remove the window's `SDL_WINDOW_RESIZABLE` flag and
1094
+ * allow/disallow user resizing of the window. This is a no-op if the window's
1095
+ * resizable state already matches the requested state.
775
1096
  *
776
- * \param window The window of which to change the resizable state.
777
- * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow.
1097
+ * You can't change the resizable state of a fullscreen window.
778
1098
  *
779
- * \note You can't change the resizable state of a fullscreen window.
1099
+ * \param window the window of which to change the resizable state
1100
+ * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow
780
1101
  *
781
- * \sa SDL_GetWindowFlags()
1102
+ * \since This function is available since SDL 2.0.5.
1103
+ *
1104
+ * \sa SDL_GetWindowFlags
782
1105
  */
783
1106
  extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window,
784
1107
  SDL_bool resizable);
785
1108
 
786
1109
  /**
787
- * \brief Show a window.
1110
+ * Set the window to always be above the others.
788
1111
  *
789
- * \sa SDL_HideWindow()
1112
+ * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This
1113
+ * will bring the window to the front and keep the window above the rest.
1114
+ *
1115
+ * \param window The window of which to change the always on top state
1116
+ * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to
1117
+ * disable
1118
+ *
1119
+ * \since This function is available since SDL 2.0.16.
1120
+ *
1121
+ * \sa SDL_GetWindowFlags
1122
+ */
1123
+ extern DECLSPEC void SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window * window,
1124
+ SDL_bool on_top);
1125
+
1126
+ /**
1127
+ * Show a window.
1128
+ *
1129
+ * \param window the window to show
1130
+ *
1131
+ * \since This function is available since SDL 2.0.0.
1132
+ *
1133
+ * \sa SDL_HideWindow
1134
+ * \sa SDL_RaiseWindow
790
1135
  */
791
1136
  extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window);
792
1137
 
793
1138
  /**
794
- * \brief Hide a window.
1139
+ * Hide a window.
795
1140
  *
796
- * \sa SDL_ShowWindow()
1141
+ * \param window the window to hide
1142
+ *
1143
+ * \since This function is available since SDL 2.0.0.
1144
+ *
1145
+ * \sa SDL_ShowWindow
797
1146
  */
798
1147
  extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window);
799
1148
 
800
1149
  /**
801
- * \brief Raise a window above other windows and set the input focus.
1150
+ * Raise a window above other windows and set the input focus.
1151
+ *
1152
+ * \param window the window to raise
1153
+ *
1154
+ * \since This function is available since SDL 2.0.0.
802
1155
  */
803
1156
  extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window);
804
1157
 
805
1158
  /**
806
- * \brief Make a window as large as possible.
1159
+ * Make a window as large as possible.
807
1160
  *
808
- * \sa SDL_RestoreWindow()
1161
+ * \param window the window to maximize
1162
+ *
1163
+ * \since This function is available since SDL 2.0.0.
1164
+ *
1165
+ * \sa SDL_MinimizeWindow
1166
+ * \sa SDL_RestoreWindow
809
1167
  */
810
1168
  extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window);
811
1169
 
812
1170
  /**
813
- * \brief Minimize a window to an iconic representation.
1171
+ * Minimize a window to an iconic representation.
814
1172
  *
815
- * \sa SDL_RestoreWindow()
1173
+ * \param window the window to minimize
1174
+ *
1175
+ * \since This function is available since SDL 2.0.0.
1176
+ *
1177
+ * \sa SDL_MaximizeWindow
1178
+ * \sa SDL_RestoreWindow
816
1179
  */
817
1180
  extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
818
1181
 
819
1182
  /**
820
- * \brief Restore the size and position of a minimized or maximized window.
1183
+ * Restore the size and position of a minimized or maximized window.
821
1184
  *
822
- * \sa SDL_MaximizeWindow()
823
- * \sa SDL_MinimizeWindow()
1185
+ * \param window the window to restore
1186
+ *
1187
+ * \since This function is available since SDL 2.0.0.
1188
+ *
1189
+ * \sa SDL_MaximizeWindow
1190
+ * \sa SDL_MinimizeWindow
824
1191
  */
825
1192
  extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window);
826
1193
 
827
1194
  /**
828
- * \brief Set a window's fullscreen state.
1195
+ * Set a window's fullscreen state.
829
1196
  *
830
- * \return 0 on success, or -1 if setting the display mode failed.
1197
+ * `flags` may be `SDL_WINDOW_FULLSCREEN`, for "real" fullscreen with a
1198
+ * videomode change; `SDL_WINDOW_FULLSCREEN_DESKTOP` for "fake" fullscreen
1199
+ * that takes the size of the desktop; and 0 for windowed mode.
831
1200
  *
832
- * \sa SDL_SetWindowDisplayMode()
833
- * \sa SDL_GetWindowDisplayMode()
1201
+ * \param window the window to change
1202
+ * \param flags `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_FULLSCREEN_DESKTOP` or 0
1203
+ * \returns 0 on success or a negative error code on failure; call
1204
+ * SDL_GetError() for more information.
1205
+ *
1206
+ * \since This function is available since SDL 2.0.0.
1207
+ *
1208
+ * \sa SDL_GetWindowDisplayMode
1209
+ * \sa SDL_SetWindowDisplayMode
834
1210
  */
835
1211
  extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window,
836
1212
  Uint32 flags);
837
1213
 
838
1214
  /**
839
- * \brief Get the SDL surface associated with the window.
1215
+ * Get the SDL surface associated with the window.
840
1216
  *
841
- * \return The window's framebuffer surface, or NULL on error.
1217
+ * A new surface will be created with the optimal format for the window, if
1218
+ * necessary. This surface will be freed when the window is destroyed. Do not
1219
+ * free this surface.
842
1220
  *
843
- * A new surface will be created with the optimal format for the window,
844
- * if necessary. This surface will be freed when the window is destroyed.
1221
+ * This surface will be invalidated if the window is resized. After resizing a
1222
+ * window this function must be called again to return a valid surface.
845
1223
  *
846
- * \note You may not combine this with 3D or the rendering API on this window.
1224
+ * You may not combine this with 3D or the rendering API on this window.
847
1225
  *
848
- * \sa SDL_UpdateWindowSurface()
849
- * \sa SDL_UpdateWindowSurfaceRects()
1226
+ * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`.
1227
+ *
1228
+ * \param window the window to query
1229
+ * \returns the surface associated with the window, or NULL on failure; call
1230
+ * SDL_GetError() for more information.
1231
+ *
1232
+ * \since This function is available since SDL 2.0.0.
1233
+ *
1234
+ * \sa SDL_UpdateWindowSurface
1235
+ * \sa SDL_UpdateWindowSurfaceRects
850
1236
  */
851
1237
  extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window);
852
1238
 
853
1239
  /**
854
- * \brief Copy the window surface to the screen.
1240
+ * Copy the window surface to the screen.
1241
+ *
1242
+ * This is the function you use to reflect any changes to the surface on the
1243
+ * screen.
855
1244
  *
856
- * \return 0 on success, or -1 on error.
1245
+ * This function is equivalent to the SDL 1.2 API SDL_Flip().
857
1246
  *
858
- * \sa SDL_GetWindowSurface()
859
- * \sa SDL_UpdateWindowSurfaceRects()
1247
+ * \param window the window to update
1248
+ * \returns 0 on success or a negative error code on failure; call
1249
+ * SDL_GetError() for more information.
1250
+ *
1251
+ * \since This function is available since SDL 2.0.0.
1252
+ *
1253
+ * \sa SDL_GetWindowSurface
1254
+ * \sa SDL_UpdateWindowSurfaceRects
860
1255
  */
861
1256
  extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window);
862
1257
 
863
1258
  /**
864
- * \brief Copy a number of rectangles on the window surface to the screen.
1259
+ * Copy areas of the window surface to the screen.
1260
+ *
1261
+ * This is the function you use to reflect changes to portions of the surface
1262
+ * on the screen.
1263
+ *
1264
+ * This function is equivalent to the SDL 1.2 API SDL_UpdateRects().
865
1265
  *
866
- * \return 0 on success, or -1 on error.
1266
+ * \param window the window to update
1267
+ * \param rects an array of SDL_Rect structures representing areas of the
1268
+ * surface to copy
1269
+ * \param numrects the number of rectangles
1270
+ * \returns 0 on success or a negative error code on failure; call
1271
+ * SDL_GetError() for more information.
867
1272
  *
868
- * \sa SDL_GetWindowSurface()
869
- * \sa SDL_UpdateWindowSurface()
1273
+ * \since This function is available since SDL 2.0.0.
1274
+ *
1275
+ * \sa SDL_GetWindowSurface
1276
+ * \sa SDL_UpdateWindowSurface
870
1277
  */
871
1278
  extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window,
872
1279
  const SDL_Rect * rects,
873
1280
  int numrects);
874
1281
 
875
1282
  /**
876
- * \brief Set a window's input grab mode.
1283
+ * Set a window's input grab mode.
877
1284
  *
878
- * \param window The window for which the input grab mode should be set.
879
- * \param grabbed This is SDL_TRUE to grab input, and SDL_FALSE to release input.
1285
+ * When input is grabbed, the mouse is confined to the window. This function
1286
+ * will also grab the keyboard if `SDL_HINT_GRAB_KEYBOARD` is set. To grab the
1287
+ * keyboard without also grabbing the mouse, use SDL_SetWindowKeyboardGrab().
880
1288
  *
881
- * If the caller enables a grab while another window is currently grabbed,
882
- * the other window loses its grab in favor of the caller's window.
1289
+ * If the caller enables a grab while another window is currently grabbed, the
1290
+ * other window loses its grab in favor of the caller's window.
883
1291
  *
884
- * \sa SDL_GetWindowGrab()
1292
+ * \param window the window for which the input grab mode should be set
1293
+ * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release input
1294
+ *
1295
+ * \since This function is available since SDL 2.0.0.
1296
+ *
1297
+ * \sa SDL_GetGrabbedWindow
1298
+ * \sa SDL_GetWindowGrab
885
1299
  */
886
1300
  extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
887
1301
  SDL_bool grabbed);
888
1302
 
889
1303
  /**
890
- * \brief Get a window's input grab mode.
1304
+ * Set a window's keyboard grab mode.
891
1305
  *
892
- * \return This returns SDL_TRUE if input is grabbed, and SDL_FALSE otherwise.
1306
+ * Keyboard grab enables capture of system keyboard shortcuts like Alt+Tab or
1307
+ * the Meta/Super key. Note that not all system keyboard shortcuts can be
1308
+ * captured by applications (one example is Ctrl+Alt+Del on Windows).
893
1309
  *
894
- * \sa SDL_SetWindowGrab()
1310
+ * This is primarily intended for specialized applications such as VNC clients
1311
+ * or VM frontends. Normal games should not use keyboard grab.
1312
+ *
1313
+ * When keyboard grab is enabled, SDL will continue to handle Alt+Tab when the
1314
+ * window is full-screen to ensure the user is not trapped in your
1315
+ * application. If you have a custom keyboard shortcut to exit fullscreen
1316
+ * mode, you may suppress this behavior with
1317
+ * `SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED`.
1318
+ *
1319
+ * If the caller enables a grab while another window is currently grabbed, the
1320
+ * other window loses its grab in favor of the caller's window.
1321
+ *
1322
+ * \param window The window for which the keyboard grab mode should be set.
1323
+ * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release.
1324
+ *
1325
+ * \since This function is available since SDL 2.0.16.
1326
+ *
1327
+ * \sa SDL_GetWindowKeyboardGrab
1328
+ * \sa SDL_SetWindowMouseGrab
1329
+ * \sa SDL_SetWindowGrab
1330
+ */
1331
+ extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window,
1332
+ SDL_bool grabbed);
1333
+
1334
+ /**
1335
+ * Set a window's mouse grab mode.
1336
+ *
1337
+ * Mouse grab confines the mouse cursor to the window.
1338
+ *
1339
+ * \param window The window for which the mouse grab mode should be set.
1340
+ *
1341
+ * \since This function is available since SDL 2.0.16.
1342
+ *
1343
+ * \sa SDL_GetWindowMouseGrab
1344
+ * \sa SDL_SetWindowKeyboardGrab
1345
+ * \sa SDL_SetWindowGrab
1346
+ */
1347
+ extern DECLSPEC void SDLCALL SDL_SetWindowMouseGrab(SDL_Window * window,
1348
+ SDL_bool grabbed);
1349
+
1350
+ /**
1351
+ * Get a window's input grab mode.
1352
+ *
1353
+ * \param window the window to query
1354
+ * \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise.
1355
+ *
1356
+ * \since This function is available since SDL 2.0.0.
1357
+ *
1358
+ * \sa SDL_SetWindowGrab
895
1359
  */
896
1360
  extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window);
897
1361
 
898
1362
  /**
899
- * \brief Get the window that currently has an input grab enabled.
1363
+ * Get a window's keyboard grab mode.
900
1364
  *
901
- * \return This returns the window if input is grabbed, and NULL otherwise.
1365
+ * \param window the window to query
1366
+ * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise.
902
1367
  *
903
- * \sa SDL_SetWindowGrab()
1368
+ * \since This function is available since SDL 2.0.16.
1369
+ *
1370
+ * \sa SDL_SetWindowKeyboardGrab
1371
+ * \sa SDL_GetWindowGrab
1372
+ */
1373
+ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window);
1374
+
1375
+ /**
1376
+ * Get a window's mouse grab mode.
1377
+ *
1378
+ * \param window the window to query
1379
+ * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
1380
+ *
1381
+ * \since This function is available since SDL 2.0.16.
1382
+ *
1383
+ * \sa SDL_SetWindowKeyboardGrab
1384
+ * \sa SDL_GetWindowGrab
1385
+ */
1386
+ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window * window);
1387
+
1388
+ /**
1389
+ * Get the window that currently has an input grab enabled.
1390
+ *
1391
+ * \returns the window if input is grabbed or NULL otherwise.
1392
+ *
1393
+ * \since This function is available since SDL 2.0.4.
1394
+ *
1395
+ * \sa SDL_GetWindowGrab
1396
+ * \sa SDL_SetWindowGrab
904
1397
  */
905
1398
  extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void);
906
1399
 
907
1400
  /**
908
- * \brief Set the brightness (gamma correction) for a window.
1401
+ * Confines the cursor to the specified area of a window.
1402
+ *
1403
+ * Note that this does NOT grab the cursor, it only defines the area a cursor
1404
+ * is restricted to when the window has mouse focus.
1405
+ *
1406
+ * \param window The window that will be associated with the barrier.
1407
+ * \param rect A rectangle area in window-relative coordinates. If NULL the
1408
+ * barrier for the specified window will be destroyed.
1409
+ * \returns 0 on success or a negative error code on failure; call
1410
+ * SDL_GetError() for more information.
1411
+ *
1412
+ * \since This function is available since SDL 2.0.18.
1413
+ *
1414
+ * \sa SDL_GetWindowMouseRect
1415
+ * \sa SDL_SetWindowMouseGrab
1416
+ */
1417
+ extern DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window * window, const SDL_Rect * rect);
1418
+
1419
+ /**
1420
+ * Get the mouse confinement rectangle of a window.
1421
+ *
1422
+ * \param window The window to query
1423
+ * \returns A pointer to the mouse confinement rectangle of a window, or NULL
1424
+ * if there isn't one.
909
1425
  *
910
- * \return 0 on success, or -1 if setting the brightness isn't supported.
1426
+ * \since This function is available since SDL 2.0.18.
911
1427
  *
912
- * \sa SDL_GetWindowBrightness()
913
- * \sa SDL_SetWindowGammaRamp()
1428
+ * \sa SDL_SetWindowMouseRect
1429
+ */
1430
+ extern DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * window);
1431
+
1432
+ /**
1433
+ * Set the brightness (gamma multiplier) for a given window's display.
1434
+ *
1435
+ * Despite the name and signature, this method sets the brightness of the
1436
+ * entire display, not an individual window. A window is considered to be
1437
+ * owned by the display that contains the window's center pixel. (The index of
1438
+ * this display can be retrieved using SDL_GetWindowDisplayIndex().) The
1439
+ * brightness set will not follow the window if it is moved to another
1440
+ * display.
1441
+ *
1442
+ * Many platforms will refuse to set the display brightness in modern times.
1443
+ * You are better off using a shader to adjust gamma during rendering, or
1444
+ * something similar.
1445
+ *
1446
+ * \param window the window used to select the display whose brightness will
1447
+ * be changed
1448
+ * \param brightness the brightness (gamma multiplier) value to set where 0.0
1449
+ * is completely dark and 1.0 is normal brightness
1450
+ * \returns 0 on success or a negative error code on failure; call
1451
+ * SDL_GetError() for more information.
1452
+ *
1453
+ * \since This function is available since SDL 2.0.0.
1454
+ *
1455
+ * \sa SDL_GetWindowBrightness
1456
+ * \sa SDL_SetWindowGammaRamp
914
1457
  */
915
1458
  extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float brightness);
916
1459
 
917
1460
  /**
918
- * \brief Get the brightness (gamma correction) for a window.
1461
+ * Get the brightness (gamma multiplier) for a given window's display.
1462
+ *
1463
+ * Despite the name and signature, this method retrieves the brightness of the
1464
+ * entire display, not an individual window. A window is considered to be
1465
+ * owned by the display that contains the window's center pixel. (The index of
1466
+ * this display can be retrieved using SDL_GetWindowDisplayIndex().)
1467
+ *
1468
+ * \param window the window used to select the display whose brightness will
1469
+ * be queried
1470
+ * \returns the brightness for the display where 0.0 is completely dark and
1471
+ * 1.0 is normal brightness.
919
1472
  *
920
- * \return The last brightness value passed to SDL_SetWindowBrightness()
1473
+ * \since This function is available since SDL 2.0.0.
921
1474
  *
922
- * \sa SDL_SetWindowBrightness()
1475
+ * \sa SDL_SetWindowBrightness
923
1476
  */
924
1477
  extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window);
925
1478
 
926
1479
  /**
927
- * \brief Set the opacity for a window
1480
+ * Set the opacity for a window.
928
1481
  *
929
- * \param window The window which will be made transparent or opaque
930
- * \param opacity Opacity (0.0f - transparent, 1.0f - opaque) This will be
931
- * clamped internally between 0.0f and 1.0f.
1482
+ * The parameter `opacity` will be clamped internally between 0.0f
1483
+ * (transparent) and 1.0f (opaque).
932
1484
  *
933
- * \return 0 on success, or -1 if setting the opacity isn't supported.
1485
+ * This function also returns -1 if setting the opacity isn't supported.
934
1486
  *
935
- * \sa SDL_GetWindowOpacity()
1487
+ * \param window the window which will be made transparent or opaque
1488
+ * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque)
1489
+ * \returns 0 on success or a negative error code on failure; call
1490
+ * SDL_GetError() for more information.
1491
+ *
1492
+ * \since This function is available since SDL 2.0.5.
1493
+ *
1494
+ * \sa SDL_GetWindowOpacity
936
1495
  */
937
1496
  extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window * window, float opacity);
938
1497
 
939
1498
  /**
940
- * \brief Get the opacity of a window.
1499
+ * Get the opacity of a window.
1500
+ *
1501
+ * If transparency isn't supported on this platform, opacity will be reported
1502
+ * as 1.0f without error.
941
1503
  *
942
- * If transparency isn't supported on this platform, opacity will be reported
943
- * as 1.0f without error.
1504
+ * The parameter `opacity` is ignored if it is NULL.
944
1505
  *
945
- * \param window The window in question.
946
- * \param out_opacity Opacity (0.0f - transparent, 1.0f - opaque)
1506
+ * This function also returns -1 if an invalid window was provided.
947
1507
  *
948
- * \return 0 on success, or -1 on error (invalid window, etc).
1508
+ * \param window the window to get the current opacity value from
1509
+ * \param out_opacity the float filled in (0.0f - transparent, 1.0f - opaque)
1510
+ * \returns 0 on success or a negative error code on failure; call
1511
+ * SDL_GetError() for more information.
949
1512
  *
950
- * \sa SDL_SetWindowOpacity()
1513
+ * \since This function is available since SDL 2.0.5.
1514
+ *
1515
+ * \sa SDL_SetWindowOpacity
951
1516
  */
952
1517
  extern DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window * window, float * out_opacity);
953
1518
 
954
1519
  /**
955
- * \brief Sets the window as a modal for another window (TODO: reconsider this function and/or its name)
1520
+ * Set the window as a modal for another window.
956
1521
  *
957
- * \param modal_window The window that should be modal
958
- * \param parent_window The parent window
1522
+ * \param modal_window the window that should be set modal
1523
+ * \param parent_window the parent window for the modal window
1524
+ * \returns 0 on success or a negative error code on failure; call
1525
+ * SDL_GetError() for more information.
959
1526
  *
960
- * \return 0 on success, or -1 otherwise.
1527
+ * \since This function is available since SDL 2.0.5.
961
1528
  */
962
1529
  extern DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window * modal_window, SDL_Window * parent_window);
963
1530
 
964
1531
  /**
965
- * \brief Explicitly sets input focus to the window.
1532
+ * Explicitly set input focus to the window.
966
1533
  *
967
- * You almost certainly want SDL_RaiseWindow() instead of this function. Use
968
- * this with caution, as you might give focus to a window that's completely
969
- * obscured by other windows.
1534
+ * You almost certainly want SDL_RaiseWindow() instead of this function. Use
1535
+ * this with caution, as you might give focus to a window that is completely
1536
+ * obscured by other windows.
970
1537
  *
971
- * \param window The window that should get the input focus
1538
+ * \param window the window that should get the input focus
1539
+ * \returns 0 on success or a negative error code on failure; call
1540
+ * SDL_GetError() for more information.
972
1541
  *
973
- * \return 0 on success, or -1 otherwise.
974
- * \sa SDL_RaiseWindow()
1542
+ * \since This function is available since SDL 2.0.5.
1543
+ *
1544
+ * \sa SDL_RaiseWindow
975
1545
  */
976
1546
  extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window);
977
1547
 
978
1548
  /**
979
- * \brief Set the gamma ramp for a window.
1549
+ * Set the gamma ramp for the display that owns a given window.
1550
+ *
1551
+ * Set the gamma translation table for the red, green, and blue channels of
1552
+ * the video hardware. Each table is an array of 256 16-bit quantities,
1553
+ * representing a mapping between the input and output for that channel. The
1554
+ * input is the index into the array, and the output is the 16-bit gamma value
1555
+ * at that index, scaled to the output color precision.
980
1556
  *
981
- * \param window The window for which the gamma ramp should be set.
982
- * \param red The translation table for the red channel, or NULL.
983
- * \param green The translation table for the green channel, or NULL.
984
- * \param blue The translation table for the blue channel, or NULL.
1557
+ * Despite the name and signature, this method sets the gamma ramp of the
1558
+ * entire display, not an individual window. A window is considered to be
1559
+ * owned by the display that contains the window's center pixel. (The index of
1560
+ * this display can be retrieved using SDL_GetWindowDisplayIndex().) The gamma
1561
+ * ramp set will not follow the window if it is moved to another display.
985
1562
  *
986
- * \return 0 on success, or -1 if gamma ramps are unsupported.
1563
+ * \param window the window used to select the display whose gamma ramp will
1564
+ * be changed
1565
+ * \param red a 256 element array of 16-bit quantities representing the
1566
+ * translation table for the red channel, or NULL
1567
+ * \param green a 256 element array of 16-bit quantities representing the
1568
+ * translation table for the green channel, or NULL
1569
+ * \param blue a 256 element array of 16-bit quantities representing the
1570
+ * translation table for the blue channel, or NULL
1571
+ * \returns 0 on success or a negative error code on failure; call
1572
+ * SDL_GetError() for more information.
987
1573
  *
988
- * Set the gamma translation table for the red, green, and blue channels
989
- * of the video hardware. Each table is an array of 256 16-bit quantities,
990
- * representing a mapping between the input and output for that channel.
991
- * The input is the index into the array, and the output is the 16-bit
992
- * gamma value at that index, scaled to the output color precision.
1574
+ * \since This function is available since SDL 2.0.0.
993
1575
  *
994
- * \sa SDL_GetWindowGammaRamp()
1576
+ * \sa SDL_GetWindowGammaRamp
995
1577
  */
996
1578
  extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window,
997
1579
  const Uint16 * red,
@@ -999,19 +1581,27 @@ extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window,
999
1581
  const Uint16 * blue);
1000
1582
 
1001
1583
  /**
1002
- * \brief Get the gamma ramp for a window.
1584
+ * Get the gamma ramp for a given window's display.
1003
1585
  *
1004
- * \param window The window from which the gamma ramp should be queried.
1005
- * \param red A pointer to a 256 element array of 16-bit quantities to hold
1006
- * the translation table for the red channel, or NULL.
1007
- * \param green A pointer to a 256 element array of 16-bit quantities to hold
1008
- * the translation table for the green channel, or NULL.
1009
- * \param blue A pointer to a 256 element array of 16-bit quantities to hold
1010
- * the translation table for the blue channel, or NULL.
1586
+ * Despite the name and signature, this method retrieves the gamma ramp of the
1587
+ * entire display, not an individual window. A window is considered to be
1588
+ * owned by the display that contains the window's center pixel. (The index of
1589
+ * this display can be retrieved using SDL_GetWindowDisplayIndex().)
1011
1590
  *
1012
- * \return 0 on success, or -1 if gamma ramps are unsupported.
1591
+ * \param window the window used to select the display whose gamma ramp will
1592
+ * be queried
1593
+ * \param red a 256 element array of 16-bit quantities filled in with the
1594
+ * translation table for the red channel, or NULL
1595
+ * \param green a 256 element array of 16-bit quantities filled in with the
1596
+ * translation table for the green channel, or NULL
1597
+ * \param blue a 256 element array of 16-bit quantities filled in with the
1598
+ * translation table for the blue channel, or NULL
1599
+ * \returns 0 on success or a negative error code on failure; call
1600
+ * SDL_GetError() for more information.
1013
1601
  *
1014
- * \sa SDL_SetWindowGammaRamp()
1602
+ * \since This function is available since SDL 2.0.0.
1603
+ *
1604
+ * \sa SDL_SetWindowGammaRamp
1015
1605
  */
1016
1606
  extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window,
1017
1607
  Uint16 * red,
@@ -1019,9 +1609,9 @@ extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window,
1019
1609
  Uint16 * blue);
1020
1610
 
1021
1611
  /**
1022
- * \brief Possible return values from the SDL_HitTest callback.
1612
+ * Possible return values from the SDL_HitTest callback.
1023
1613
  *
1024
- * \sa SDL_HitTest
1614
+ * \sa SDL_HitTest
1025
1615
  */
1026
1616
  typedef enum
1027
1617
  {
@@ -1038,82 +1628,129 @@ typedef enum
1038
1628
  } SDL_HitTestResult;
1039
1629
 
1040
1630
  /**
1041
- * \brief Callback used for hit-testing.
1631
+ * Callback used for hit-testing.
1632
+ *
1633
+ * \param win the SDL_Window where hit-testing was set on
1634
+ * \param area an SDL_Point which should be hit-tested
1635
+ * \param data what was passed as `callback_data` to SDL_SetWindowHitTest()
1636
+ * \return an SDL_HitTestResult value.
1042
1637
  *
1043
- * \sa SDL_SetWindowHitTest
1638
+ * \sa SDL_SetWindowHitTest
1044
1639
  */
1045
1640
  typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
1046
1641
  const SDL_Point *area,
1047
1642
  void *data);
1048
1643
 
1049
1644
  /**
1050
- * \brief Provide a callback that decides if a window region has special properties.
1645
+ * Provide a callback that decides if a window region has special properties.
1051
1646
  *
1052
- * Normally windows are dragged and resized by decorations provided by the
1053
- * system window manager (a title bar, borders, etc), but for some apps, it
1054
- * makes sense to drag them from somewhere else inside the window itself; for
1055
- * example, one might have a borderless window that wants to be draggable
1056
- * from any part, or simulate its own title bar, etc.
1647
+ * Normally windows are dragged and resized by decorations provided by the
1648
+ * system window manager (a title bar, borders, etc), but for some apps, it
1649
+ * makes sense to drag them from somewhere else inside the window itself; for
1650
+ * example, one might have a borderless window that wants to be draggable from
1651
+ * any part, or simulate its own title bar, etc.
1057
1652
  *
1058
- * This function lets the app provide a callback that designates pieces of
1059
- * a given window as special. This callback is run during event processing
1060
- * if we need to tell the OS to treat a region of the window specially; the
1061
- * use of this callback is known as "hit testing."
1653
+ * This function lets the app provide a callback that designates pieces of a
1654
+ * given window as special. This callback is run during event processing if we
1655
+ * need to tell the OS to treat a region of the window specially; the use of
1656
+ * this callback is known as "hit testing."
1062
1657
  *
1063
- * Mouse input may not be delivered to your application if it is within
1064
- * a special area; the OS will often apply that input to moving the window or
1065
- * resizing the window and not deliver it to the application.
1658
+ * Mouse input may not be delivered to your application if it is within a
1659
+ * special area; the OS will often apply that input to moving the window or
1660
+ * resizing the window and not deliver it to the application.
1066
1661
  *
1067
- * Specifying NULL for a callback disables hit-testing. Hit-testing is
1068
- * disabled by default.
1662
+ * Specifying NULL for a callback disables hit-testing. Hit-testing is
1663
+ * disabled by default.
1069
1664
  *
1070
- * Platforms that don't support this functionality will return -1
1071
- * unconditionally, even if you're attempting to disable hit-testing.
1665
+ * Platforms that don't support this functionality will return -1
1666
+ * unconditionally, even if you're attempting to disable hit-testing.
1072
1667
  *
1073
- * Your callback may fire at any time, and its firing does not indicate any
1074
- * specific behavior (for example, on Windows, this certainly might fire
1075
- * when the OS is deciding whether to drag your window, but it fires for lots
1076
- * of other reasons, too, some unrelated to anything you probably care about
1077
- * _and when the mouse isn't actually at the location it is testing_).
1078
- * Since this can fire at any time, you should try to keep your callback
1079
- * efficient, devoid of allocations, etc.
1668
+ * Your callback may fire at any time, and its firing does not indicate any
1669
+ * specific behavior (for example, on Windows, this certainly might fire when
1670
+ * the OS is deciding whether to drag your window, but it fires for lots of
1671
+ * other reasons, too, some unrelated to anything you probably care about _and
1672
+ * when the mouse isn't actually at the location it is testing_). Since this
1673
+ * can fire at any time, you should try to keep your callback efficient,
1674
+ * devoid of allocations, etc.
1080
1675
  *
1081
- * \param window The window to set hit-testing on.
1082
- * \param callback The callback to call when doing a hit-test.
1083
- * \param callback_data An app-defined void pointer passed to the callback.
1084
- * \return 0 on success, -1 on error (including unsupported).
1676
+ * \param window the window to set hit-testing on
1677
+ * \param callback the function to call when doing a hit-test
1678
+ * \param callback_data an app-defined void pointer passed to **callback**
1679
+ * \returns 0 on success or -1 on error (including unsupported); call
1680
+ * SDL_GetError() for more information.
1681
+ *
1682
+ * \since This function is available since SDL 2.0.4.
1085
1683
  */
1086
1684
  extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window,
1087
1685
  SDL_HitTest callback,
1088
1686
  void *callback_data);
1089
1687
 
1090
1688
  /**
1091
- * \brief Destroy a window.
1689
+ * Request a window to demand attention from the user.
1690
+ *
1691
+ * \param window the window to be flashed
1692
+ * \param operation the flash operation
1693
+ * \returns 0 on success or a negative error code on failure; call
1694
+ * SDL_GetError() for more information.
1695
+ *
1696
+ * \since This function is available since SDL 2.0.16.
1697
+ */
1698
+ extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, SDL_FlashOperation operation);
1699
+
1700
+ /**
1701
+ * Destroy a window.
1702
+ *
1703
+ * If `window` is NULL, this function will return immediately after setting
1704
+ * the SDL error message to "Invalid window". See SDL_GetError().
1705
+ *
1706
+ * \param window the window to destroy
1707
+ *
1708
+ * \since This function is available since SDL 2.0.0.
1709
+ *
1710
+ * \sa SDL_CreateWindow
1711
+ * \sa SDL_CreateWindowFrom
1092
1712
  */
1093
1713
  extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window * window);
1094
1714
 
1095
1715
 
1096
1716
  /**
1097
- * \brief Returns whether the screensaver is currently enabled (default off).
1717
+ * Check whether the screensaver is currently enabled.
1718
+ *
1719
+ * The screensaver is disabled by default since SDL 2.0.2. Before SDL 2.0.2
1720
+ * the screensaver was enabled by default.
1721
+ *
1722
+ * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`.
1723
+ *
1724
+ * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is
1725
+ * disabled.
1098
1726
  *
1099
- * \sa SDL_EnableScreenSaver()
1100
- * \sa SDL_DisableScreenSaver()
1727
+ * \since This function is available since SDL 2.0.0.
1728
+ *
1729
+ * \sa SDL_DisableScreenSaver
1730
+ * \sa SDL_EnableScreenSaver
1101
1731
  */
1102
1732
  extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenSaverEnabled(void);
1103
1733
 
1104
1734
  /**
1105
- * \brief Allow the screen to be blanked by a screensaver
1735
+ * Allow the screen to be blanked by a screen saver.
1736
+ *
1737
+ * \since This function is available since SDL 2.0.0.
1106
1738
  *
1107
- * \sa SDL_IsScreenSaverEnabled()
1108
- * \sa SDL_DisableScreenSaver()
1739
+ * \sa SDL_DisableScreenSaver
1740
+ * \sa SDL_IsScreenSaverEnabled
1109
1741
  */
1110
1742
  extern DECLSPEC void SDLCALL SDL_EnableScreenSaver(void);
1111
1743
 
1112
1744
  /**
1113
- * \brief Prevent the screen from being blanked by a screensaver
1745
+ * Prevent the screen from being blanked by a screen saver.
1746
+ *
1747
+ * If you disable the screensaver, it is automatically re-enabled when SDL
1748
+ * quits.
1749
+ *
1750
+ * \since This function is available since SDL 2.0.0.
1114
1751
  *
1115
- * \sa SDL_IsScreenSaverEnabled()
1116
- * \sa SDL_EnableScreenSaver()
1752
+ * \sa SDL_EnableScreenSaver
1753
+ * \sa SDL_IsScreenSaverEnabled
1117
1754
  */
1118
1755
  extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
1119
1756
 
@@ -1124,147 +1761,316 @@ extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
1124
1761
  /* @{ */
1125
1762
 
1126
1763
  /**
1127
- * \brief Dynamically load an OpenGL library.
1764
+ * Dynamically load an OpenGL library.
1128
1765
  *
1129
- * \param path The platform dependent OpenGL library name, or NULL to open the
1130
- * default OpenGL library.
1766
+ * This should be done after initializing the video driver, but before
1767
+ * creating any OpenGL windows. If no OpenGL library is loaded, the default
1768
+ * library will be loaded upon creation of the first OpenGL window.
1131
1769
  *
1132
- * \return 0 on success, or -1 if the library couldn't be loaded.
1770
+ * If you do this, you need to retrieve all of the GL functions used in your
1771
+ * program from the dynamic library using SDL_GL_GetProcAddress().
1133
1772
  *
1134
- * This should be done after initializing the video driver, but before
1135
- * creating any OpenGL windows. If no OpenGL library is loaded, the default
1136
- * library will be loaded upon creation of the first OpenGL window.
1773
+ * \param path the platform dependent OpenGL library name, or NULL to open the
1774
+ * default OpenGL library
1775
+ * \returns 0 on success or a negative error code on failure; call
1776
+ * SDL_GetError() for more information.
1137
1777
  *
1138
- * \note If you do this, you need to retrieve all of the GL functions used in
1139
- * your program from the dynamic library using SDL_GL_GetProcAddress().
1778
+ * \since This function is available since SDL 2.0.0.
1140
1779
  *
1141
- * \sa SDL_GL_GetProcAddress()
1142
- * \sa SDL_GL_UnloadLibrary()
1780
+ * \sa SDL_GL_GetProcAddress
1781
+ * \sa SDL_GL_UnloadLibrary
1143
1782
  */
1144
1783
  extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
1145
1784
 
1146
1785
  /**
1147
- * \brief Get the address of an OpenGL function.
1786
+ * Get an OpenGL function by name.
1787
+ *
1788
+ * If the GL library is loaded at runtime with SDL_GL_LoadLibrary(), then all
1789
+ * GL functions must be retrieved this way. Usually this is used to retrieve
1790
+ * function pointers to OpenGL extensions.
1791
+ *
1792
+ * There are some quirks to looking up OpenGL functions that require some
1793
+ * extra care from the application. If you code carefully, you can handle
1794
+ * these quirks without any platform-specific code, though:
1795
+ *
1796
+ * - On Windows, function pointers are specific to the current GL context;
1797
+ * this means you need to have created a GL context and made it current
1798
+ * before calling SDL_GL_GetProcAddress(). If you recreate your context or
1799
+ * create a second context, you should assume that any existing function
1800
+ * pointers aren't valid to use with it. This is (currently) a
1801
+ * Windows-specific limitation, and in practice lots of drivers don't suffer
1802
+ * this limitation, but it is still the way the wgl API is documented to
1803
+ * work and you should expect crashes if you don't respect it. Store a copy
1804
+ * of the function pointers that comes and goes with context lifespan.
1805
+ * - On X11, function pointers returned by this function are valid for any
1806
+ * context, and can even be looked up before a context is created at all.
1807
+ * This means that, for at least some common OpenGL implementations, if you
1808
+ * look up a function that doesn't exist, you'll get a non-NULL result that
1809
+ * is _NOT_ safe to call. You must always make sure the function is actually
1810
+ * available for a given GL context before calling it, by checking for the
1811
+ * existence of the appropriate extension with SDL_GL_ExtensionSupported(),
1812
+ * or verifying that the version of OpenGL you're using offers the function
1813
+ * as core functionality.
1814
+ * - Some OpenGL drivers, on all platforms, *will* return NULL if a function
1815
+ * isn't supported, but you can't count on this behavior. Check for
1816
+ * extensions you use, and if you get a NULL anyway, act as if that
1817
+ * extension wasn't available. This is probably a bug in the driver, but you
1818
+ * can code defensively for this scenario anyhow.
1819
+ * - Just because you're on Linux/Unix, don't assume you'll be using X11.
1820
+ * Next-gen display servers are waiting to replace it, and may or may not
1821
+ * make the same promises about function pointers.
1822
+ * - OpenGL function pointers must be declared `APIENTRY` as in the example
1823
+ * code. This will ensure the proper calling convention is followed on
1824
+ * platforms where this matters (Win32) thereby avoiding stack corruption.
1825
+ *
1826
+ * \param proc the name of an OpenGL function
1827
+ * \returns a pointer to the named OpenGL function. The returned pointer
1828
+ * should be cast to the appropriate function signature.
1829
+ *
1830
+ * \since This function is available since SDL 2.0.0.
1831
+ *
1832
+ * \sa SDL_GL_ExtensionSupported
1833
+ * \sa SDL_GL_LoadLibrary
1834
+ * \sa SDL_GL_UnloadLibrary
1148
1835
  */
1149
1836
  extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc);
1150
1837
 
1151
1838
  /**
1152
- * \brief Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
1839
+ * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
1153
1840
  *
1154
- * \sa SDL_GL_LoadLibrary()
1841
+ * \since This function is available since SDL 2.0.0.
1842
+ *
1843
+ * \sa SDL_GL_LoadLibrary
1155
1844
  */
1156
1845
  extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void);
1157
1846
 
1158
1847
  /**
1159
- * \brief Return true if an OpenGL extension is supported for the current
1160
- * context.
1848
+ * Check if an OpenGL extension is supported for the current context.
1849
+ *
1850
+ * This function operates on the current GL context; you must have created a
1851
+ * context and it must be current before calling this function. Do not assume
1852
+ * that all contexts you create will have the same set of extensions
1853
+ * available, or that recreating an existing context will offer the same
1854
+ * extensions again.
1855
+ *
1856
+ * While it's probably not a massive overhead, this function is not an O(1)
1857
+ * operation. Check the extensions you care about after creating the GL
1858
+ * context and save that information somewhere instead of calling the function
1859
+ * every time you need to know.
1860
+ *
1861
+ * \param extension the name of the extension to check
1862
+ * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise.
1863
+ *
1864
+ * \since This function is available since SDL 2.0.0.
1161
1865
  */
1162
1866
  extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char
1163
1867
  *extension);
1164
1868
 
1165
1869
  /**
1166
- * \brief Reset all previously set OpenGL context attributes to their default values
1870
+ * Reset all previously set OpenGL context attributes to their default values.
1871
+ *
1872
+ * \since This function is available since SDL 2.0.2.
1873
+ *
1874
+ * \sa SDL_GL_GetAttribute
1875
+ * \sa SDL_GL_SetAttribute
1167
1876
  */
1168
1877
  extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
1169
1878
 
1170
1879
  /**
1171
- * \brief Set an OpenGL window attribute before window creation.
1880
+ * Set an OpenGL window attribute before window creation.
1881
+ *
1882
+ * This function sets the OpenGL attribute `attr` to `value`. The requested
1883
+ * attributes should be set before creating an OpenGL window. You should use
1884
+ * SDL_GL_GetAttribute() to check the values after creating the OpenGL
1885
+ * context, since the values obtained can differ from the requested ones.
1172
1886
  *
1173
- * \return 0 on success, or -1 if the attribute could not be set.
1887
+ * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to set
1888
+ * \param value the desired value for the attribute
1889
+ * \returns 0 on success or a negative error code on failure; call
1890
+ * SDL_GetError() for more information.
1891
+ *
1892
+ * \since This function is available since SDL 2.0.0.
1893
+ *
1894
+ * \sa SDL_GL_GetAttribute
1895
+ * \sa SDL_GL_ResetAttributes
1174
1896
  */
1175
1897
  extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
1176
1898
 
1177
1899
  /**
1178
- * \brief Get the actual value for an attribute from the current context.
1900
+ * Get the actual value for an attribute from the current context.
1901
+ *
1902
+ * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to get
1903
+ * \param value a pointer filled in with the current value of `attr`
1904
+ * \returns 0 on success or a negative error code on failure; call
1905
+ * SDL_GetError() for more information.
1179
1906
  *
1180
- * \return 0 on success, or -1 if the attribute could not be retrieved.
1181
- * The integer at \c value will be modified in either case.
1907
+ * \since This function is available since SDL 2.0.0.
1908
+ *
1909
+ * \sa SDL_GL_ResetAttributes
1910
+ * \sa SDL_GL_SetAttribute
1182
1911
  */
1183
1912
  extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value);
1184
1913
 
1185
1914
  /**
1186
- * \brief Create an OpenGL context for use with an OpenGL window, and make it
1187
- * current.
1915
+ * Create an OpenGL context for an OpenGL window, and make it current.
1916
+ *
1917
+ * Windows users new to OpenGL should note that, for historical reasons, GL
1918
+ * functions added after OpenGL version 1.1 are not available by default.
1919
+ * Those functions must be loaded at run-time, either with an OpenGL
1920
+ * extension-handling library or with SDL_GL_GetProcAddress() and its related
1921
+ * functions.
1188
1922
  *
1189
- * \sa SDL_GL_DeleteContext()
1923
+ * SDL_GLContext is an alias for `void *`. It's opaque to the application.
1924
+ *
1925
+ * \param window the window to associate with the context
1926
+ * \returns the OpenGL context associated with `window` or NULL on error; call
1927
+ * SDL_GetError() for more details.
1928
+ *
1929
+ * \since This function is available since SDL 2.0.0.
1930
+ *
1931
+ * \sa SDL_GL_DeleteContext
1932
+ * \sa SDL_GL_MakeCurrent
1190
1933
  */
1191
1934
  extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *
1192
1935
  window);
1193
1936
 
1194
1937
  /**
1195
- * \brief Set up an OpenGL context for rendering into an OpenGL window.
1938
+ * Set up an OpenGL context for rendering into an OpenGL window.
1939
+ *
1940
+ * The context must have been created with a compatible window.
1196
1941
  *
1197
- * \note The context must have been created with a compatible window.
1942
+ * \param window the window to associate with the context
1943
+ * \param context the OpenGL context to associate with the window
1944
+ * \returns 0 on success or a negative error code on failure; call
1945
+ * SDL_GetError() for more information.
1946
+ *
1947
+ * \since This function is available since SDL 2.0.0.
1948
+ *
1949
+ * \sa SDL_GL_CreateContext
1198
1950
  */
1199
1951
  extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_Window * window,
1200
1952
  SDL_GLContext context);
1201
1953
 
1202
1954
  /**
1203
- * \brief Get the currently active OpenGL window.
1955
+ * Get the currently active OpenGL window.
1956
+ *
1957
+ * \returns the currently active OpenGL window on success or NULL on failure;
1958
+ * call SDL_GetError() for more information.
1959
+ *
1960
+ * \since This function is available since SDL 2.0.0.
1204
1961
  */
1205
1962
  extern DECLSPEC SDL_Window* SDLCALL SDL_GL_GetCurrentWindow(void);
1206
1963
 
1207
1964
  /**
1208
- * \brief Get the currently active OpenGL context.
1965
+ * Get the currently active OpenGL context.
1966
+ *
1967
+ * \returns the currently active OpenGL context or NULL on failure; call
1968
+ * SDL_GetError() for more information.
1969
+ *
1970
+ * \since This function is available since SDL 2.0.0.
1971
+ *
1972
+ * \sa SDL_GL_MakeCurrent
1209
1973
  */
1210
1974
  extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void);
1211
1975
 
1212
1976
  /**
1213
- * \brief Get the size of a window's underlying drawable in pixels (for use
1214
- * with glViewport).
1977
+ * Get the size of a window's underlying drawable in pixels.
1215
1978
  *
1216
- * \param window Window from which the drawable size should be queried
1217
- * \param w Pointer to variable for storing the width in pixels, may be NULL
1218
- * \param h Pointer to variable for storing the height in pixels, may be NULL
1979
+ * This returns info useful for calling glViewport().
1219
1980
  *
1220
1981
  * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
1221
- * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
1222
- * platform with high-DPI support (Apple calls this "Retina"), and not disabled
1223
- * by the SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
1982
+ * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a
1983
+ * platform with high-DPI support (Apple calls this "Retina"), and not
1984
+ * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
1224
1985
  *
1225
- * \sa SDL_GetWindowSize()
1226
- * \sa SDL_CreateWindow()
1986
+ * \param window the window from which the drawable size should be queried
1987
+ * \param w a pointer to variable for storing the width in pixels, may be NULL
1988
+ * \param h a pointer to variable for storing the height in pixels, may be
1989
+ * NULL
1990
+ *
1991
+ * \since This function is available since SDL 2.0.1.
1992
+ *
1993
+ * \sa SDL_CreateWindow
1994
+ * \sa SDL_GetWindowSize
1227
1995
  */
1228
1996
  extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w,
1229
1997
  int *h);
1230
1998
 
1231
1999
  /**
1232
- * \brief Set the swap interval for the current OpenGL context.
2000
+ * Set the swap interval for the current OpenGL context.
2001
+ *
2002
+ * Some systems allow specifying -1 for the interval, to enable adaptive
2003
+ * vsync. Adaptive vsync works the same as vsync, but if you've already missed
2004
+ * the vertical retrace for a given frame, it swaps buffers immediately, which
2005
+ * might be less jarring for the user during occasional framerate drops. If an
2006
+ * application requests adaptive vsync and the system does not support it,
2007
+ * this function will fail and return -1. In such a case, you should probably
2008
+ * retry the call with 1 for the interval.
2009
+ *
2010
+ * Adaptive vsync is implemented for some glX drivers with
2011
+ * GLX_EXT_swap_control_tear:
2012
+ *
2013
+ * https://www.opengl.org/registry/specs/EXT/glx_swap_control_tear.txt
2014
+ *
2015
+ * and for some Windows drivers with WGL_EXT_swap_control_tear:
2016
+ *
2017
+ * https://www.opengl.org/registry/specs/EXT/wgl_swap_control_tear.txt
2018
+ *
2019
+ * Read more on the Khronos wiki:
2020
+ * https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync
1233
2021
  *
1234
- * \param interval 0 for immediate updates, 1 for updates synchronized with the
1235
- * vertical retrace. If the system supports it, you may
1236
- * specify -1 to allow late swaps to happen immediately
1237
- * instead of waiting for the next retrace.
2022
+ * \param interval 0 for immediate updates, 1 for updates synchronized with
2023
+ * the vertical retrace, -1 for adaptive vsync
2024
+ * \returns 0 on success or -1 if setting the swap interval is not supported;
2025
+ * call SDL_GetError() for more information.
1238
2026
  *
1239
- * \return 0 on success, or -1 if setting the swap interval is not supported.
2027
+ * \since This function is available since SDL 2.0.0.
1240
2028
  *
1241
- * \sa SDL_GL_GetSwapInterval()
2029
+ * \sa SDL_GL_GetSwapInterval
1242
2030
  */
1243
2031
  extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
1244
2032
 
1245
2033
  /**
1246
- * \brief Get the swap interval for the current OpenGL context.
2034
+ * Get the swap interval for the current OpenGL context.
1247
2035
  *
1248
- * \return 0 if there is no vertical retrace synchronization, 1 if the buffer
2036
+ * If the system can't determine the swap interval, or there isn't a valid
2037
+ * current context, this function will return 0 as a safe default.
2038
+ *
2039
+ * \returns 0 if there is no vertical retrace synchronization, 1 if the buffer
1249
2040
  * swap is synchronized with the vertical retrace, and -1 if late
1250
- * swaps happen immediately instead of waiting for the next retrace.
1251
- * If the system can't determine the swap interval, or there isn't a
1252
- * valid current context, this will return 0 as a safe default.
2041
+ * swaps happen immediately instead of waiting for the next retrace;
2042
+ * call SDL_GetError() for more information.
2043
+ *
2044
+ * \since This function is available since SDL 2.0.0.
1253
2045
  *
1254
- * \sa SDL_GL_SetSwapInterval()
2046
+ * \sa SDL_GL_SetSwapInterval
1255
2047
  */
1256
2048
  extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
1257
2049
 
1258
2050
  /**
1259
- * \brief Swap the OpenGL buffers for a window, if double-buffering is
1260
- * supported.
2051
+ * Update a window with OpenGL rendering.
2052
+ *
2053
+ * This is used with double-buffered OpenGL contexts, which are the default.
2054
+ *
2055
+ * On macOS, make sure you bind 0 to the draw framebuffer before swapping the
2056
+ * window, otherwise nothing will happen. If you aren't using
2057
+ * glBindFramebuffer(), this is the default and you won't have to do anything
2058
+ * extra.
2059
+ *
2060
+ * \param window the window to change
2061
+ *
2062
+ * \since This function is available since SDL 2.0.0.
1261
2063
  */
1262
2064
  extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window);
1263
2065
 
1264
2066
  /**
1265
- * \brief Delete an OpenGL context.
2067
+ * Delete an OpenGL context.
2068
+ *
2069
+ * \param context the OpenGL context to be deleted
2070
+ *
2071
+ * \since This function is available since SDL 2.0.0.
1266
2072
  *
1267
- * \sa SDL_GL_CreateContext()
2073
+ * \sa SDL_GL_CreateContext
1268
2074
  */
1269
2075
  extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context);
1270
2076