ruby2d 0.10.0 → 0.11.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (387) 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/build_config.rb +13 -0
  172. data/assets/wasm/libmruby.a +0 -0
  173. data/assets/wasm/template.html +17 -0
  174. data/assets/windows/glew/README.md +10 -0
  175. data/assets/windows/glew/glew.h +23686 -0
  176. data/assets/{mingw/lib → windows/glew}/libglew32.a +0 -0
  177. data/assets/windows/mingw-w64-x86_64/bin/mrbc.exe +0 -0
  178. data/assets/windows/mingw-w64-x86_64/lib/libFLAC.a +0 -0
  179. data/assets/windows/mingw-w64-x86_64/lib/libLerc.a +0 -0
  180. data/assets/windows/mingw-w64-x86_64/lib/libSDL2.a +0 -0
  181. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_image.a +0 -0
  182. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_mixer.a +0 -0
  183. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_ttf.a +0 -0
  184. data/assets/windows/mingw-w64-x86_64/lib/libbrotlicommon.a +0 -0
  185. data/assets/windows/mingw-w64-x86_64/lib/libbrotlidec.a +0 -0
  186. data/assets/windows/mingw-w64-x86_64/lib/libbz2.a +0 -0
  187. data/assets/windows/mingw-w64-x86_64/lib/libdeflate.a +0 -0
  188. data/assets/windows/mingw-w64-x86_64/lib/libfreetype.a +0 -0
  189. data/assets/windows/mingw-w64-x86_64/lib/libglew32.a +0 -0
  190. data/assets/windows/mingw-w64-x86_64/lib/libgraphite2.a +0 -0
  191. data/assets/windows/mingw-w64-x86_64/lib/libharfbuzz.a +0 -0
  192. data/assets/windows/mingw-w64-x86_64/lib/libjbig.a +0 -0
  193. data/assets/windows/mingw-w64-x86_64/lib/libjpeg.a +0 -0
  194. data/assets/windows/mingw-w64-x86_64/lib/liblzma.a +0 -0
  195. data/assets/windows/mingw-w64-x86_64/lib/libmodplug.a +0 -0
  196. data/assets/windows/mingw-w64-x86_64/lib/libmpg123.a +0 -0
  197. data/assets/windows/mingw-w64-x86_64/lib/libmruby.a +0 -0
  198. data/assets/windows/mingw-w64-x86_64/lib/libogg.a +0 -0
  199. data/assets/windows/mingw-w64-x86_64/lib/libopus.a +0 -0
  200. data/assets/windows/mingw-w64-x86_64/lib/libopusfile.a +0 -0
  201. data/assets/windows/mingw-w64-x86_64/lib/libpng16.a +0 -0
  202. data/assets/windows/mingw-w64-x86_64/lib/libsndfile.a +0 -0
  203. data/assets/windows/mingw-w64-x86_64/lib/libssp.a +0 -0
  204. data/assets/windows/mingw-w64-x86_64/lib/libstdc++.a +0 -0
  205. data/assets/windows/mingw-w64-x86_64/lib/libtiff.a +0 -0
  206. data/assets/windows/mingw-w64-x86_64/lib/libvorbis.a +0 -0
  207. data/assets/windows/mingw-w64-x86_64/lib/libvorbisfile.a +0 -0
  208. data/assets/windows/mingw-w64-x86_64/lib/libwebp.a +0 -0
  209. data/assets/windows/mingw-w64-x86_64/lib/libz.a +0 -0
  210. data/assets/windows/mingw-w64-x86_64/lib/libzstd.a +0 -0
  211. data/assets/{ios → xcode/ios}/Assets.xcassets/AppIcon.appiconset/Contents.json +0 -0
  212. data/assets/{ios → xcode/ios}/Assets.xcassets/Contents.json +0 -0
  213. data/assets/{ios → xcode/ios}/Base.lproj/LaunchScreen.storyboard +0 -0
  214. data/assets/{ios → xcode/ios}/Info.plist +0 -0
  215. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mrbconf.h +0 -0
  216. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/array.h +0 -0
  217. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/boxing_nan.h +0 -0
  218. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/boxing_no.h +0 -0
  219. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/boxing_word.h +0 -0
  220. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/class.h +0 -0
  221. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/common.h +0 -0
  222. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/compile.h +0 -0
  223. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/data.h +0 -0
  224. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/debug.h +0 -0
  225. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/dump.h +0 -0
  226. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/error.h +0 -0
  227. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/gc.h +0 -0
  228. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/hash.h +0 -0
  229. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/irep.h +0 -0
  230. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/istruct.h +0 -0
  231. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/khash.h +0 -0
  232. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/numeric.h +0 -0
  233. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/object.h +0 -0
  234. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/opcode.h +0 -0
  235. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/ops.h +0 -0
  236. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/proc.h +0 -0
  237. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/range.h +0 -0
  238. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/re.h +0 -0
  239. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/string.h +0 -0
  240. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/throw.h +0 -0
  241. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/value.h +0 -0
  242. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/variable.h +0 -0
  243. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/version.h +0 -0
  244. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby.h +0 -0
  245. data/assets/{ios → xcode/ios}/MRuby.framework/Info.plist +0 -0
  246. data/assets/{ios → xcode/ios}/MRuby.framework/MRuby +0 -0
  247. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.pbxproj +0 -0
  248. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.xcworkspace/contents.xcworkspacedata +0 -0
  249. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist +0 -0
  250. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/MyApp.xcscmblueprint +0 -0
  251. data/assets/{ios → xcode/ios}/main.c +0 -0
  252. 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
  253. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Back.imagestacklayer/Contents.json +0 -0
  254. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Contents.json +0 -0
  255. 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
  256. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Front.imagestacklayer/Contents.json +0 -0
  257. 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
  258. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Middle.imagestacklayer/Contents.json +0 -0
  259. 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
  260. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Back.imagestacklayer/Contents.json +0 -0
  261. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Contents.json +0 -0
  262. 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
  263. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Front.imagestacklayer/Contents.json +0 -0
  264. 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
  265. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Middle.imagestacklayer/Contents.json +0 -0
  266. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/Contents.json +0 -0
  267. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/Top Shelf Image Wide.imageset/Contents.json +0 -0
  268. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/Top Shelf Image.imageset/Contents.json +0 -0
  269. data/assets/{tvos → xcode/tvos}/Assets.xcassets/Contents.json +0 -0
  270. data/assets/{tvos → xcode/tvos}/Assets.xcassets/LaunchImage.launchimage/Contents.json +0 -0
  271. data/assets/{tvos → xcode/tvos}/Info.plist +0 -0
  272. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mrbconf.h +0 -0
  273. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/array.h +0 -0
  274. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/boxing_nan.h +0 -0
  275. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/boxing_no.h +0 -0
  276. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/boxing_word.h +0 -0
  277. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/class.h +0 -0
  278. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/common.h +0 -0
  279. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/compile.h +0 -0
  280. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/data.h +0 -0
  281. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/debug.h +0 -0
  282. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/dump.h +0 -0
  283. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/error.h +0 -0
  284. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/gc.h +0 -0
  285. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/hash.h +0 -0
  286. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/irep.h +0 -0
  287. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/istruct.h +0 -0
  288. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/khash.h +0 -0
  289. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/numeric.h +0 -0
  290. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/object.h +0 -0
  291. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/opcode.h +0 -0
  292. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/ops.h +0 -0
  293. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/proc.h +0 -0
  294. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/range.h +0 -0
  295. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/re.h +0 -0
  296. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/string.h +0 -0
  297. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/throw.h +0 -0
  298. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/value.h +0 -0
  299. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/variable.h +0 -0
  300. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/version.h +0 -0
  301. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby.h +0 -0
  302. data/assets/{tvos → xcode/tvos}/MRuby.framework/Info.plist +0 -0
  303. data/assets/{tvos → xcode/tvos}/MRuby.framework/MRuby +0 -0
  304. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.pbxproj +0 -0
  305. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.xcworkspace/contents.xcworkspacedata +0 -0
  306. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist +0 -0
  307. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/MyApp.xcscmblueprint +0 -0
  308. data/assets/{tvos → xcode/tvos}/main.c +0 -0
  309. data/bin/ruby2d +3 -4
  310. data/ext/ruby2d/extconf.rb +68 -46
  311. data/ext/ruby2d/font.c +35 -0
  312. data/ext/ruby2d/gl.c +9 -58
  313. data/ext/ruby2d/gl2.c +8 -83
  314. data/ext/ruby2d/gl3.c +57 -116
  315. data/ext/ruby2d/gles.c +130 -151
  316. data/ext/ruby2d/image.c +16 -96
  317. data/ext/ruby2d/ruby2d.c +265 -298
  318. data/ext/ruby2d/ruby2d.h +69 -159
  319. data/ext/ruby2d/sound.c +1 -1
  320. data/ext/ruby2d/text.c +20 -114
  321. data/ext/ruby2d/window.c +257 -219
  322. data/lib/ruby2d/circle.rb +3 -1
  323. data/lib/ruby2d/cli/build.rb +239 -59
  324. data/lib/ruby2d/cli/colorize.rb +5 -4
  325. data/lib/ruby2d/cli/platform.rb +17 -0
  326. data/lib/ruby2d/font.rb +26 -1
  327. data/lib/ruby2d/image.rb +22 -17
  328. data/lib/ruby2d/line.rb +3 -1
  329. data/lib/ruby2d/quad.rb +3 -1
  330. data/lib/ruby2d/rectangle.rb +1 -1
  331. data/lib/ruby2d/renderable.rb +0 -12
  332. data/lib/ruby2d/sound.rb +25 -0
  333. data/lib/ruby2d/sprite.rb +44 -89
  334. data/lib/ruby2d/square.rb +1 -1
  335. data/lib/ruby2d/text.rb +40 -20
  336. data/lib/ruby2d/texture.rb +28 -0
  337. data/lib/ruby2d/tileset.rb +47 -28
  338. data/lib/ruby2d/triangle.rb +3 -1
  339. data/lib/ruby2d/version.rb +1 -1
  340. data/lib/ruby2d/vertices.rb +89 -0
  341. data/lib/ruby2d/window.rb +13 -3
  342. data/lib/ruby2d.rb +16 -20
  343. metadata +249 -153
  344. data/assets/README.md +0 -22
  345. data/assets/Rakefile +0 -85
  346. data/assets/macos/lib/libFLAC.a +0 -0
  347. data/assets/macos/lib/libSDL2.a +0 -0
  348. data/assets/macos/lib/libSDL2_image.a +0 -0
  349. data/assets/macos/lib/libSDL2_ttf.a +0 -0
  350. data/assets/macos/lib/libfreetype.a +0 -0
  351. data/assets/macos/lib/libjpeg.a +0 -0
  352. data/assets/macos/lib/libpng16.a +0 -0
  353. data/assets/macos/lib/libtiff.a +0 -0
  354. data/assets/macos/lib/libvorbis.a +0 -0
  355. data/assets/macos/lib/libvorbisfile.a +0 -0
  356. data/assets/macos/lib/libwebp.a +0 -0
  357. data/assets/mingw/bin/SDL2.dll +0 -0
  358. data/assets/mingw/bin/SDL2_image.dll +0 -0
  359. data/assets/mingw/bin/SDL2_mixer.dll +0 -0
  360. data/assets/mingw/bin/SDL2_ttf.dll +0 -0
  361. data/assets/mingw/bin/glew32.dll +0 -0
  362. data/assets/mingw/bin/libFLAC-8.dll +0 -0
  363. data/assets/mingw/bin/libfreetype-6.dll +0 -0
  364. data/assets/mingw/bin/libjpeg-9.dll +0 -0
  365. data/assets/mingw/bin/libmodplug-1.dll +0 -0
  366. data/assets/mingw/bin/libmpg123-0.dll +0 -0
  367. data/assets/mingw/bin/libogg-0.dll +0 -0
  368. data/assets/mingw/bin/libopus-0.dll +0 -0
  369. data/assets/mingw/bin/libopusfile-0.dll +0 -0
  370. data/assets/mingw/bin/libpng16-16.dll +0 -0
  371. data/assets/mingw/bin/libtiff-5.dll +0 -0
  372. data/assets/mingw/bin/libvorbis-0.dll +0 -0
  373. data/assets/mingw/bin/libvorbisfile-3.dll +0 -0
  374. data/assets/mingw/bin/libwebp-7.dll +0 -0
  375. data/assets/mingw/bin/zlib1.dll +0 -0
  376. data/assets/mingw/lib/libSDL2.dll.a +0 -0
  377. data/assets/mingw/lib/libSDL2_image.a +0 -0
  378. data/assets/mingw/lib/libSDL2_image.dll.a +0 -0
  379. data/assets/mingw/lib/libSDL2_mixer.a +0 -0
  380. data/assets/mingw/lib/libSDL2_mixer.dll.a +0 -0
  381. data/assets/mingw/lib/libSDL2_test.a +0 -0
  382. data/assets/mingw/lib/libSDL2_ttf.a +0 -0
  383. data/assets/mingw/lib/libSDL2_ttf.dll.a +0 -0
  384. data/assets/mingw/lib/libSDL2main.a +0 -0
  385. data/assets/mingw/lib/libglew32.dll.a +0 -0
  386. data/ext/ruby2d/sprite.c +0 -147
  387. data/ext/ruby2d/tileset.c +0 -30
@@ -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
@@ -59,7 +59,7 @@ extern "C" {
59
59
  #endif
60
60
 
61
61
  /**
62
- * \brief Flags used when creating a rendering context
62
+ * Flags used when creating a rendering context
63
63
  */
64
64
  typedef enum
65
65
  {
@@ -73,7 +73,7 @@ typedef enum
73
73
  } SDL_RendererFlags;
74
74
 
75
75
  /**
76
- * \brief Information on the capabilities of a render driver or context.
76
+ * Information on the capabilities of a render driver or context.
77
77
  */
78
78
  typedef struct SDL_RendererInfo
79
79
  {
@@ -86,7 +86,17 @@ typedef struct SDL_RendererInfo
86
86
  } SDL_RendererInfo;
87
87
 
88
88
  /**
89
- * \brief The scaling mode for a texture.
89
+ * Vertex structure
90
+ */
91
+ typedef struct SDL_Vertex
92
+ {
93
+ SDL_FPoint position; /**< Vertex position, in SDL_Renderer coordinates */
94
+ SDL_Color color; /**< Vertex color */
95
+ SDL_FPoint tex_coord; /**< Normalized texture coordinates, if needed */
96
+ } SDL_Vertex;
97
+
98
+ /**
99
+ * The scaling mode for a texture.
90
100
  */
91
101
  typedef enum
92
102
  {
@@ -96,7 +106,7 @@ typedef enum
96
106
  } SDL_ScaleMode;
97
107
 
98
108
  /**
99
- * \brief The access pattern allowed for a texture.
109
+ * The access pattern allowed for a texture.
100
110
  */
101
111
  typedef enum
102
112
  {
@@ -106,7 +116,7 @@ typedef enum
106
116
  } SDL_TextureAccess;
107
117
 
108
118
  /**
109
- * \brief The texture channel modulation used in SDL_RenderCopy().
119
+ * The texture channel modulation used in SDL_RenderCopy().
110
120
  */
111
121
  typedef enum
112
122
  {
@@ -116,7 +126,7 @@ typedef enum
116
126
  } SDL_TextureModulate;
117
127
 
118
128
  /**
119
- * \brief Flip constants for SDL_RenderCopyEx
129
+ * Flip constants for SDL_RenderCopyEx
120
130
  */
121
131
  typedef enum
122
132
  {
@@ -126,58 +136,71 @@ typedef enum
126
136
  } SDL_RendererFlip;
127
137
 
128
138
  /**
129
- * \brief A structure representing rendering state
139
+ * A structure representing rendering state
130
140
  */
131
141
  struct SDL_Renderer;
132
142
  typedef struct SDL_Renderer SDL_Renderer;
133
143
 
134
144
  /**
135
- * \brief An efficient driver-specific representation of pixel data
145
+ * An efficient driver-specific representation of pixel data
136
146
  */
137
147
  struct SDL_Texture;
138
148
  typedef struct SDL_Texture SDL_Texture;
139
149
 
140
-
141
150
  /* Function prototypes */
142
151
 
143
152
  /**
144
- * \brief Get the number of 2D rendering drivers available for the current
145
- * display.
153
+ * Get the number of 2D rendering drivers available for the current display.
146
154
  *
147
- * A render driver is a set of code that handles rendering and texture
148
- * management on a particular display. Normally there is only one, but
149
- * some drivers may have several available with different capabilities.
155
+ * A render driver is a set of code that handles rendering and texture
156
+ * management on a particular display. Normally there is only one, but some
157
+ * drivers may have several available with different capabilities.
150
158
  *
151
- * \sa SDL_GetRenderDriverInfo()
152
- * \sa SDL_CreateRenderer()
159
+ * There may be none if SDL was compiled without render support.
160
+ *
161
+ * \returns a number >= 0 on success or a negative error code on failure; call
162
+ * SDL_GetError() for more information.
163
+ *
164
+ * \since This function is available since SDL 2.0.0.
165
+ *
166
+ * \sa SDL_CreateRenderer
167
+ * \sa SDL_GetRenderDriverInfo
153
168
  */
154
169
  extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
155
170
 
156
171
  /**
157
- * \brief Get information about a specific 2D rendering driver for the current
158
- * display.
172
+ * Get info about a specific 2D rendering driver for the current display.
159
173
  *
160
- * \param index The index of the driver to query information about.
161
- * \param info A pointer to an SDL_RendererInfo struct to be filled with
162
- * information on the rendering driver.
174
+ * \param index the index of the driver to query information about
175
+ * \param info an SDL_RendererInfo structure to be filled with information on
176
+ * the rendering driver
177
+ * \returns 0 on success or a negative error code on failure; call
178
+ * SDL_GetError() for more information.
163
179
  *
164
- * \return 0 on success, -1 if the index was out of range.
180
+ * \since This function is available since SDL 2.0.0.
165
181
  *
166
- * \sa SDL_CreateRenderer()
182
+ * \sa SDL_CreateRenderer
183
+ * \sa SDL_GetNumRenderDrivers
167
184
  */
168
185
  extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index,
169
186
  SDL_RendererInfo * info);
170
187
 
171
188
  /**
172
- * \brief Create a window and default renderer
189
+ * Create a window and default renderer.
173
190
  *
174
- * \param width The width of the window
175
- * \param height The height of the window
176
- * \param window_flags The flags used to create the window
177
- * \param window A pointer filled with the window, or NULL on error
178
- * \param renderer A pointer filled with the renderer, or NULL on error
191
+ * \param width the width of the window
192
+ * \param height the height of the window
193
+ * \param window_flags the flags used to create the window (see
194
+ * SDL_CreateWindow())
195
+ * \param window a pointer filled with the window, or NULL on error
196
+ * \param renderer a pointer filled with the renderer, or NULL on error
197
+ * \returns 0 on success, or -1 on error; call SDL_GetError() for more
198
+ * information.
179
199
  *
180
- * \return 0 on success, or -1 on error
200
+ * \since This function is available since SDL 2.0.0.
201
+ *
202
+ * \sa SDL_CreateRenderer
203
+ * \sa SDL_CreateWindow
181
204
  */
182
205
  extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(
183
206
  int width, int height, Uint32 window_flags,
@@ -185,69 +208,116 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(
185
208
 
186
209
 
187
210
  /**
188
- * \brief Create a 2D rendering context for a window.
211
+ * Create a 2D rendering context for a window.
189
212
  *
190
- * \param window The window where rendering is displayed.
191
- * \param index The index of the rendering driver to initialize, or -1 to
192
- * initialize the first one supporting the requested flags.
193
- * \param flags ::SDL_RendererFlags.
213
+ * \param window the window where rendering is displayed
214
+ * \param index the index of the rendering driver to initialize, or -1 to
215
+ * initialize the first one supporting the requested flags
216
+ * \param flags 0, or one or more SDL_RendererFlags OR'd together
217
+ * \returns a valid rendering context or NULL if there was an error; call
218
+ * SDL_GetError() for more information.
194
219
  *
195
- * \return A valid rendering context or NULL if there was an error.
220
+ * \since This function is available since SDL 2.0.0.
196
221
  *
197
- * \sa SDL_CreateSoftwareRenderer()
198
- * \sa SDL_GetRendererInfo()
199
- * \sa SDL_DestroyRenderer()
222
+ * \sa SDL_CreateSoftwareRenderer
223
+ * \sa SDL_DestroyRenderer
224
+ * \sa SDL_GetNumRenderDrivers
225
+ * \sa SDL_GetRendererInfo
200
226
  */
201
227
  extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window,
202
228
  int index, Uint32 flags);
203
229
 
204
230
  /**
205
- * \brief Create a 2D software rendering context for a surface.
231
+ * Create a 2D software rendering context for a surface.
232
+ *
233
+ * Two other API which can be used to create SDL_Renderer:
234
+ * SDL_CreateRenderer() and SDL_CreateWindowAndRenderer(). These can _also_
235
+ * create a software renderer, but they are intended to be used with an
236
+ * SDL_Window as the final destination and not an SDL_Surface.
206
237
  *
207
- * \param surface The surface where rendering is done.
238
+ * \param surface the SDL_Surface structure representing the surface where
239
+ * rendering is done
240
+ * \returns a valid rendering context or NULL if there was an error; call
241
+ * SDL_GetError() for more information.
208
242
  *
209
- * \return A valid rendering context or NULL if there was an error.
243
+ * \since This function is available since SDL 2.0.0.
210
244
  *
211
- * \sa SDL_CreateRenderer()
212
- * \sa SDL_DestroyRenderer()
245
+ * \sa SDL_CreateRenderer
246
+ * \sa SDL_CreateWindowRenderer
247
+ * \sa SDL_DestroyRenderer
213
248
  */
214
249
  extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface * surface);
215
250
 
216
251
  /**
217
- * \brief Get the renderer associated with a window.
252
+ * Get the renderer associated with a window.
253
+ *
254
+ * \param window the window to query
255
+ * \returns the rendering context on success or NULL on failure; call
256
+ * SDL_GetError() for more information.
257
+ *
258
+ * \since This function is available since SDL 2.0.0.
259
+ *
260
+ * \sa SDL_CreateRenderer
218
261
  */
219
262
  extern DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window * window);
220
263
 
221
264
  /**
222
- * \brief Get information about a rendering context.
265
+ * Get information about a rendering context.
266
+ *
267
+ * \param renderer the rendering context
268
+ * \param info an SDL_RendererInfo structure filled with information about the
269
+ * current renderer
270
+ * \returns 0 on success or a negative error code on failure; call
271
+ * SDL_GetError() for more information.
272
+ *
273
+ * \since This function is available since SDL 2.0.0.
274
+ *
275
+ * \sa SDL_CreateRenderer
223
276
  */
224
277
  extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer,
225
278
  SDL_RendererInfo * info);
226
279
 
227
280
  /**
228
- * \brief Get the output size in pixels of a rendering context.
281
+ * Get the output size in pixels of a rendering context.
282
+ *
283
+ * Due to high-dpi displays, you might end up with a rendering context that
284
+ * has more pixels than the window that contains it, so use this instead of
285
+ * SDL_GetWindowSize() to decide how much drawing area you have.
286
+ *
287
+ * \param renderer the rendering context
288
+ * \param w an int filled with the width
289
+ * \param h an int filled with the height
290
+ * \returns 0 on success or a negative error code on failure; call
291
+ * SDL_GetError() for more information.
292
+ *
293
+ * \since This function is available since SDL 2.0.0.
294
+ *
295
+ * \sa SDL_GetRenderer
229
296
  */
230
297
  extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer,
231
298
  int *w, int *h);
232
299
 
233
300
  /**
234
- * \brief Create a texture for a rendering context.
301
+ * Create a texture for a rendering context.
235
302
  *
236
- * \param renderer The renderer.
237
- * \param format The format of the texture.
238
- * \param access One of the enumerated values in ::SDL_TextureAccess.
239
- * \param w The width of the texture in pixels.
240
- * \param h The height of the texture in pixels.
303
+ * You can set the texture scaling method by setting
304
+ * `SDL_HINT_RENDER_SCALE_QUALITY` before creating the texture.
241
305
  *
242
- * \return The created texture is returned, or NULL if no rendering context was
243
- * active, the format was unsupported, or the width or height were out
244
- * of range.
306
+ * \param renderer the rendering context
307
+ * \param format one of the enumerated values in SDL_PixelFormatEnum
308
+ * \param access one of the enumerated values in SDL_TextureAccess
309
+ * \param w the width of the texture in pixels
310
+ * \param h the height of the texture in pixels
311
+ * \returns a pointer to the created texture or NULL if no rendering context
312
+ * was active, the format was unsupported, or the width or height
313
+ * were out of range; call SDL_GetError() for more information.
245
314
  *
246
- * \note The contents of the texture are not defined at creation.
315
+ * \since This function is available since SDL 2.0.0.
247
316
  *
248
- * \sa SDL_QueryTexture()
249
- * \sa SDL_UpdateTexture()
250
- * \sa SDL_DestroyTexture()
317
+ * \sa SDL_CreateTextureFromSurface
318
+ * \sa SDL_DestroyTexture
319
+ * \sa SDL_QueryTexture
320
+ * \sa SDL_UpdateTexture
251
321
  */
252
322
  extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer,
253
323
  Uint32 format,
@@ -255,194 +325,290 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer,
255
325
  int h);
256
326
 
257
327
  /**
258
- * \brief Create a texture from an existing surface.
328
+ * Create a texture from an existing surface.
329
+ *
330
+ * The surface is not modified or freed by this function.
331
+ *
332
+ * The SDL_TextureAccess hint for the created texture is
333
+ * `SDL_TEXTUREACCESS_STATIC`.
259
334
  *
260
- * \param renderer The renderer.
261
- * \param surface The surface containing pixel data used to fill the texture.
335
+ * The pixel format of the created texture may be different from the pixel
336
+ * format of the surface. Use SDL_QueryTexture() to query the pixel format of
337
+ * the texture.
262
338
  *
263
- * \return The created texture is returned, or NULL on error.
339
+ * \param renderer the rendering context
340
+ * \param surface the SDL_Surface structure containing pixel data used to fill
341
+ * the texture
342
+ * \returns the created texture or NULL on failure; call SDL_GetError() for
343
+ * more information.
264
344
  *
265
- * \note The surface is not modified or freed by this function.
345
+ * \since This function is available since SDL 2.0.0.
266
346
  *
267
- * \sa SDL_QueryTexture()
268
- * \sa SDL_DestroyTexture()
347
+ * \sa SDL_CreateTexture
348
+ * \sa SDL_DestroyTexture
349
+ * \sa SDL_QueryTexture
269
350
  */
270
351
  extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * renderer, SDL_Surface * surface);
271
352
 
272
353
  /**
273
- * \brief Query the attributes of a texture
354
+ * Query the attributes of a texture.
274
355
  *
275
- * \param texture A texture to be queried.
276
- * \param format A pointer filled in with the raw format of the texture. The
277
- * actual format may differ, but pixel transfers will use this
278
- * format.
279
- * \param access A pointer filled in with the actual access to the texture.
280
- * \param w A pointer filled in with the width of the texture in pixels.
281
- * \param h A pointer filled in with the height of the texture in pixels.
356
+ * \param texture the texture to query
357
+ * \param format a pointer filled in with the raw format of the texture; the
358
+ * actual format may differ, but pixel transfers will use this
359
+ * format (one of the SDL_PixelFormatEnum values)
360
+ * \param access a pointer filled in with the actual access to the texture
361
+ * (one of the SDL_TextureAccess values)
362
+ * \param w a pointer filled in with the width of the texture in pixels
363
+ * \param h a pointer filled in with the height of the texture in pixels
364
+ * \returns 0 on success or a negative error code on failure; call
365
+ * SDL_GetError() for more information.
282
366
  *
283
- * \return 0 on success, or -1 if the texture is not valid.
367
+ * \since This function is available since SDL 2.0.0.
368
+ *
369
+ * \sa SDL_CreateTexture
284
370
  */
285
371
  extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture,
286
372
  Uint32 * format, int *access,
287
373
  int *w, int *h);
288
374
 
289
375
  /**
290
- * \brief Set an additional color value used in render copy operations.
376
+ * Set an additional color value multiplied into render copy operations.
377
+ *
378
+ * When this texture is rendered, during the copy operation each source color
379
+ * channel is modulated by the appropriate color value according to the
380
+ * following formula:
291
381
  *
292
- * \param texture The texture to update.
293
- * \param r The red color value multiplied into copy operations.
294
- * \param g The green color value multiplied into copy operations.
295
- * \param b The blue color value multiplied into copy operations.
382
+ * `srcC = srcC * (color / 255)`
296
383
  *
297
- * \return 0 on success, or -1 if the texture is not valid or color modulation
298
- * is not supported.
384
+ * Color modulation is not always supported by the renderer; it will return -1
385
+ * if color modulation is not supported.
299
386
  *
300
- * \sa SDL_GetTextureColorMod()
387
+ * \param texture the texture to update
388
+ * \param r the red color value multiplied into copy operations
389
+ * \param g the green color value multiplied into copy operations
390
+ * \param b the blue color value multiplied into copy operations
391
+ * \returns 0 on success or a negative error code on failure; call
392
+ * SDL_GetError() for more information.
393
+ *
394
+ * \since This function is available since SDL 2.0.0.
395
+ *
396
+ * \sa SDL_GetTextureColorMod
397
+ * \sa SDL_SetTextureAlphaMod
301
398
  */
302
399
  extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture,
303
400
  Uint8 r, Uint8 g, Uint8 b);
304
401
 
305
402
 
306
403
  /**
307
- * \brief Get the additional color value used in render copy operations.
404
+ * Get the additional color value multiplied into render copy operations.
308
405
  *
309
- * \param texture The texture to query.
310
- * \param r A pointer filled in with the current red color value.
311
- * \param g A pointer filled in with the current green color value.
312
- * \param b A pointer filled in with the current blue color value.
406
+ * \param texture the texture to query
407
+ * \param r a pointer filled in with the current red color value
408
+ * \param g a pointer filled in with the current green color value
409
+ * \param b a pointer filled in with the current blue color value
410
+ * \returns 0 on success or a negative error code on failure; call
411
+ * SDL_GetError() for more information.
313
412
  *
314
- * \return 0 on success, or -1 if the texture is not valid.
413
+ * \since This function is available since SDL 2.0.0.
315
414
  *
316
- * \sa SDL_SetTextureColorMod()
415
+ * \sa SDL_GetTextureAlphaMod
416
+ * \sa SDL_SetTextureColorMod
317
417
  */
318
418
  extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture,
319
419
  Uint8 * r, Uint8 * g,
320
420
  Uint8 * b);
321
421
 
322
422
  /**
323
- * \brief Set an additional alpha value used in render copy operations.
423
+ * Set an additional alpha value multiplied into render copy operations.
424
+ *
425
+ * When this texture is rendered, during the copy operation the source alpha
426
+ * value is modulated by this alpha value according to the following formula:
427
+ *
428
+ * `srcA = srcA * (alpha / 255)`
429
+ *
430
+ * Alpha modulation is not always supported by the renderer; it will return -1
431
+ * if alpha modulation is not supported.
324
432
  *
325
- * \param texture The texture to update.
326
- * \param alpha The alpha value multiplied into copy operations.
433
+ * \param texture the texture to update
434
+ * \param alpha the source alpha value multiplied into copy operations
435
+ * \returns 0 on success or a negative error code on failure; call
436
+ * SDL_GetError() for more information.
327
437
  *
328
- * \return 0 on success, or -1 if the texture is not valid or alpha modulation
329
- * is not supported.
438
+ * \since This function is available since SDL 2.0.0.
330
439
  *
331
- * \sa SDL_GetTextureAlphaMod()
440
+ * \sa SDL_GetTextureAlphaMod
441
+ * \sa SDL_SetTextureColorMod
332
442
  */
333
443
  extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture,
334
444
  Uint8 alpha);
335
445
 
336
446
  /**
337
- * \brief Get the additional alpha value used in render copy operations.
447
+ * Get the additional alpha value multiplied into render copy operations.
338
448
  *
339
- * \param texture The texture to query.
340
- * \param alpha A pointer filled in with the current alpha value.
449
+ * \param texture the texture to query
450
+ * \param alpha a pointer filled in with the current alpha value
451
+ * \returns 0 on success or a negative error code on failure; call
452
+ * SDL_GetError() for more information.
341
453
  *
342
- * \return 0 on success, or -1 if the texture is not valid.
454
+ * \since This function is available since SDL 2.0.0.
343
455
  *
344
- * \sa SDL_SetTextureAlphaMod()
456
+ * \sa SDL_GetTextureColorMod
457
+ * \sa SDL_SetTextureAlphaMod
345
458
  */
346
459
  extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture,
347
460
  Uint8 * alpha);
348
461
 
349
462
  /**
350
- * \brief Set the blend mode used for texture copy operations.
463
+ * Set the blend mode for a texture, used by SDL_RenderCopy().
351
464
  *
352
- * \param texture The texture to update.
353
- * \param blendMode ::SDL_BlendMode to use for texture blending.
465
+ * If the blend mode is not supported, the closest supported mode is chosen
466
+ * and this function returns -1.
354
467
  *
355
- * \return 0 on success, or -1 if the texture is not valid or the blend mode is
356
- * not supported.
468
+ * \param texture the texture to update
469
+ * \param blendMode the SDL_BlendMode to use for texture blending
470
+ * \returns 0 on success or a negative error code on failure; call
471
+ * SDL_GetError() for more information.
357
472
  *
358
- * \note If the blend mode is not supported, the closest supported mode is
359
- * chosen.
473
+ * \since This function is available since SDL 2.0.0.
360
474
  *
361
- * \sa SDL_GetTextureBlendMode()
475
+ * \sa SDL_GetTextureBlendMode
476
+ * \sa SDL_RenderCopy
362
477
  */
363
478
  extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture,
364
479
  SDL_BlendMode blendMode);
365
480
 
366
481
  /**
367
- * \brief Get the blend mode used for texture copy operations.
482
+ * Get the blend mode used for texture copy operations.
368
483
  *
369
- * \param texture The texture to query.
370
- * \param blendMode A pointer filled in with the current blend mode.
484
+ * \param texture the texture to query
485
+ * \param blendMode a pointer filled in with the current SDL_BlendMode
486
+ * \returns 0 on success or a negative error code on failure; call
487
+ * SDL_GetError() for more information.
371
488
  *
372
- * \return 0 on success, or -1 if the texture is not valid.
489
+ * \since This function is available since SDL 2.0.0.
373
490
  *
374
- * \sa SDL_SetTextureBlendMode()
491
+ * \sa SDL_SetTextureBlendMode
375
492
  */
376
493
  extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture,
377
494
  SDL_BlendMode *blendMode);
378
495
 
379
496
  /**
380
- * \brief Set the scale mode used for texture scale operations.
497
+ * Set the scale mode used for texture scale operations.
381
498
  *
382
- * \param texture The texture to update.
383
- * \param scaleMode ::SDL_ScaleMode to use for texture scaling.
499
+ * If the scale mode is not supported, the closest supported mode is chosen.
384
500
  *
385
- * \return 0 on success, or -1 if the texture is not valid.
501
+ * \param texture The texture to update.
502
+ * \param scaleMode the SDL_ScaleMode to use for texture scaling.
503
+ * \returns 0 on success, or -1 if the texture is not valid.
386
504
  *
387
- * \note If the scale mode is not supported, the closest supported mode is
388
- * chosen.
505
+ * \since This function is available since SDL 2.0.12.
389
506
  *
390
- * \sa SDL_GetTextureScaleMode()
507
+ * \sa SDL_GetTextureScaleMode
391
508
  */
392
509
  extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture,
393
510
  SDL_ScaleMode scaleMode);
394
511
 
395
512
  /**
396
- * \brief Get the scale mode used for texture scale operations.
513
+ * Get the scale mode used for texture scale operations.
397
514
  *
398
- * \param texture The texture to query.
399
- * \param scaleMode A pointer filled in with the current scale mode.
515
+ * \param texture the texture to query.
516
+ * \param scaleMode a pointer filled in with the current scale mode.
517
+ * \return 0 on success, or -1 if the texture is not valid.
400
518
  *
401
- * \return 0 on success, or -1 if the texture is not valid.
519
+ * \since This function is available since SDL 2.0.12.
402
520
  *
403
- * \sa SDL_SetTextureScaleMode()
521
+ * \sa SDL_SetTextureScaleMode
404
522
  */
405
523
  extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture,
406
524
  SDL_ScaleMode *scaleMode);
407
525
 
408
526
  /**
409
- * \brief Update the given texture rectangle with new pixel data.
527
+ * Associate a user-specified pointer with a texture.
410
528
  *
411
- * \param texture The texture to update
412
- * \param rect A pointer to the rectangle of pixels to update, or NULL to
413
- * update the entire texture.
414
- * \param pixels The raw pixel data in the format of the texture.
415
- * \param pitch The number of bytes in a row of pixel data, including padding between lines.
529
+ * \param texture the texture to update.
530
+ * \param userdata the pointer to associate with the texture.
531
+ * \returns 0 on success, or -1 if the texture is not valid.
416
532
  *
417
- * The pixel data must be in the format of the texture. The pixel format can be
418
- * queried with SDL_QueryTexture.
533
+ * \since This function is available since SDL 2.0.18.
419
534
  *
420
- * \return 0 on success, or -1 if the texture is not valid.
535
+ * \sa SDL_GetTextureUserData
536
+ */
537
+ extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture * texture,
538
+ void *userdata);
539
+
540
+ /**
541
+ * Get the user-specified pointer associated with a texture
542
+ *
543
+ * \param texture the texture to query.
544
+ * \return the pointer associated with the texture, or NULL if the texture is
545
+ * not valid.
546
+ *
547
+ * \since This function is available since SDL 2.0.18.
421
548
  *
422
- * \note This is a fairly slow function.
549
+ * \sa SDL_SetTextureUserData
550
+ */
551
+ extern DECLSPEC void * SDLCALL SDL_GetTextureUserData(SDL_Texture * texture);
552
+
553
+ /**
554
+ * Update the given texture rectangle with new pixel data.
555
+ *
556
+ * The pixel data must be in the pixel format of the texture. Use
557
+ * SDL_QueryTexture() to query the pixel format of the texture.
558
+ *
559
+ * This is a fairly slow function, intended for use with static textures that
560
+ * do not change often.
561
+ *
562
+ * If the texture is intended to be updated often, it is preferred to create
563
+ * the texture as streaming and use the locking functions referenced below.
564
+ * While this function will work with streaming textures, for optimization
565
+ * reasons you may not get the pixels back if you lock the texture afterward.
566
+ *
567
+ * \param texture the texture to update
568
+ * \param rect an SDL_Rect structure representing the area to update, or NULL
569
+ * to update the entire texture
570
+ * \param pixels the raw pixel data in the format of the texture
571
+ * \param pitch the number of bytes in a row of pixel data, including padding
572
+ * between lines
573
+ * \returns 0 on success or a negative error code on failure; call
574
+ * SDL_GetError() for more information.
575
+ *
576
+ * \since This function is available since SDL 2.0.0.
577
+ *
578
+ * \sa SDL_CreateTexture
579
+ * \sa SDL_LockTexture
580
+ * \sa SDL_UnlockTexture
423
581
  */
424
582
  extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture,
425
583
  const SDL_Rect * rect,
426
584
  const void *pixels, int pitch);
427
585
 
428
586
  /**
429
- * \brief Update a rectangle within a planar YV12 or IYUV texture with new pixel data.
587
+ * Update a rectangle within a planar YV12 or IYUV texture with new pixel
588
+ * data.
430
589
  *
431
- * \param texture The texture to update
432
- * \param rect A pointer to the rectangle of pixels to update, or NULL to
433
- * update the entire texture.
434
- * \param Yplane The raw pixel data for the Y plane.
435
- * \param Ypitch The number of bytes between rows of pixel data for the Y plane.
436
- * \param Uplane The raw pixel data for the U plane.
437
- * \param Upitch The number of bytes between rows of pixel data for the U plane.
438
- * \param Vplane The raw pixel data for the V plane.
439
- * \param Vpitch The number of bytes between rows of pixel data for the V plane.
590
+ * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
591
+ * block of Y and U/V planes in the proper order, but this function is
592
+ * available if your pixel data is not contiguous.
440
593
  *
441
- * \return 0 on success, or -1 if the texture is not valid.
594
+ * \param texture the texture to update
595
+ * \param rect a pointer to the rectangle of pixels to update, or NULL to
596
+ * update the entire texture
597
+ * \param Yplane the raw pixel data for the Y plane
598
+ * \param Ypitch the number of bytes between rows of pixel data for the Y
599
+ * plane
600
+ * \param Uplane the raw pixel data for the U plane
601
+ * \param Upitch the number of bytes between rows of pixel data for the U
602
+ * plane
603
+ * \param Vplane the raw pixel data for the V plane
604
+ * \param Vpitch the number of bytes between rows of pixel data for the V
605
+ * plane
606
+ * \returns 0 on success or -1 if the texture is not valid; call
607
+ * SDL_GetError() for more information.
442
608
  *
443
- * \note You can use SDL_UpdateTexture() as long as your pixel data is
444
- * a contiguous block of Y and U/V planes in the proper order, but
445
- * this function is available if your pixel data is not contiguous.
609
+ * \since This function is available since SDL 2.0.1.
610
+ *
611
+ * \sa SDL_UpdateTexture
446
612
  */
447
613
  extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
448
614
  const SDL_Rect * rect,
@@ -451,421 +617,771 @@ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
451
617
  const Uint8 *Vplane, int Vpitch);
452
618
 
453
619
  /**
454
- * \brief Lock a portion of the texture for write-only pixel access.
620
+ * Update a rectangle within a planar NV12 or NV21 texture with new pixels.
455
621
  *
456
- * \param texture The texture to lock for access, which was created with
457
- * ::SDL_TEXTUREACCESS_STREAMING.
458
- * \param rect A pointer to the rectangle to lock for access. If the rect
459
- * is NULL, the entire texture will be locked.
460
- * \param pixels This is filled in with a pointer to the locked pixels,
461
- * appropriately offset by the locked area.
462
- * \param pitch This is filled in with the pitch of the locked pixels.
622
+ * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
623
+ * block of NV12/21 planes in the proper order, but this function is available
624
+ * if your pixel data is not contiguous.
463
625
  *
464
- * \return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING.
626
+ * \param texture the texture to update
627
+ * \param rect a pointer to the rectangle of pixels to update, or NULL to
628
+ * update the entire texture.
629
+ * \param Yplane the raw pixel data for the Y plane.
630
+ * \param Ypitch the number of bytes between rows of pixel data for the Y
631
+ * plane.
632
+ * \param UVplane the raw pixel data for the UV plane.
633
+ * \param UVpitch the number of bytes between rows of pixel data for the UV
634
+ * plane.
635
+ * \return 0 on success, or -1 if the texture is not valid.
465
636
  *
466
- * \sa SDL_UnlockTexture()
637
+ * \since This function is available since SDL 2.0.16.
638
+ */
639
+ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
640
+ const SDL_Rect * rect,
641
+ const Uint8 *Yplane, int Ypitch,
642
+ const Uint8 *UVplane, int UVpitch);
643
+
644
+ /**
645
+ * Lock a portion of the texture for **write-only** pixel access.
646
+ *
647
+ * As an optimization, the pixels made available for editing don't necessarily
648
+ * contain the old texture data. This is a write-only operation, and if you
649
+ * need to keep a copy of the texture data you should do that at the
650
+ * application level.
651
+ *
652
+ * You must use SDL_UnlockTexture() to unlock the pixels and apply any
653
+ * changes.
654
+ *
655
+ * \param texture the texture to lock for access, which was created with
656
+ * `SDL_TEXTUREACCESS_STREAMING`
657
+ * \param rect an SDL_Rect structure representing the area to lock for access;
658
+ * NULL to lock the entire texture
659
+ * \param pixels this is filled in with a pointer to the locked pixels,
660
+ * appropriately offset by the locked area
661
+ * \param pitch this is filled in with the pitch of the locked pixels; the
662
+ * pitch is the length of one row in bytes
663
+ * \returns 0 on success or a negative error code if the texture is not valid
664
+ * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call
665
+ * SDL_GetError() for more information.
666
+ *
667
+ * \since This function is available since SDL 2.0.0.
668
+ *
669
+ * \sa SDL_UnlockTexture
467
670
  */
468
671
  extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture,
469
672
  const SDL_Rect * rect,
470
673
  void **pixels, int *pitch);
471
674
 
472
675
  /**
473
- * \brief Lock a portion of the texture for write-only pixel access.
474
- * Expose it as a SDL surface.
676
+ * Lock a portion of the texture for **write-only** pixel access, and expose
677
+ * it as a SDL surface.
678
+ *
679
+ * Besides providing an SDL_Surface instead of raw pixel data, this function
680
+ * operates like SDL_LockTexture.
681
+ *
682
+ * As an optimization, the pixels made available for editing don't necessarily
683
+ * contain the old texture data. This is a write-only operation, and if you
684
+ * need to keep a copy of the texture data you should do that at the
685
+ * application level.
686
+ *
687
+ * You must use SDL_UnlockTexture() to unlock the pixels and apply any
688
+ * changes.
475
689
  *
476
- * \param texture The texture to lock for access, which was created with
477
- * ::SDL_TEXTUREACCESS_STREAMING.
478
- * \param rect A pointer to the rectangle to lock for access. If the rect
479
- * is NULL, the entire texture will be locked.
480
- * \param surface This is filled in with a SDL surface representing the locked area
481
- * Surface is freed internally after calling SDL_UnlockTexture or SDL_DestroyTexture.
690
+ * The returned surface is freed internally after calling SDL_UnlockTexture()
691
+ * or SDL_DestroyTexture(). The caller should not free it.
482
692
  *
483
- * \return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING.
693
+ * \param texture the texture to lock for access, which was created with
694
+ * `SDL_TEXTUREACCESS_STREAMING`
695
+ * \param rect a pointer to the rectangle to lock for access. If the rect is
696
+ * NULL, the entire texture will be locked
697
+ * \param surface this is filled in with an SDL surface representing the
698
+ * locked area
699
+ * \returns 0 on success, or -1 if the texture is not valid or was not created
700
+ * with `SDL_TEXTUREACCESS_STREAMING`
484
701
  *
485
- * \sa SDL_UnlockTexture()
702
+ * \since This function is available since SDL 2.0.12.
703
+ *
704
+ * \sa SDL_LockTexture
705
+ * \sa SDL_UnlockTexture
486
706
  */
487
707
  extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
488
708
  const SDL_Rect *rect,
489
709
  SDL_Surface **surface);
490
710
 
491
711
  /**
492
- * \brief Unlock a texture, uploading the changes to video memory, if needed.
493
- * If SDL_LockTextureToSurface() was called for locking, the SDL surface is freed.
712
+ * Unlock a texture, uploading the changes to video memory, if needed.
713
+ *
714
+ * **Warning**: Please note that SDL_LockTexture() is intended to be
715
+ * write-only; it will not guarantee the previous contents of the texture will
716
+ * be provided. You must fully initialize any area of a texture that you lock
717
+ * before unlocking it, as the pixels might otherwise be uninitialized memory.
718
+ *
719
+ * Which is to say: locking and immediately unlocking a texture can result in
720
+ * corrupted textures, depending on the renderer in use.
721
+ *
722
+ * \param texture a texture locked by SDL_LockTexture()
723
+ *
724
+ * \since This function is available since SDL 2.0.0.
494
725
  *
495
- * \sa SDL_LockTexture()
496
- * \sa SDL_LockTextureToSurface()
726
+ * \sa SDL_LockTexture
497
727
  */
498
728
  extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture);
499
729
 
500
730
  /**
501
- * \brief Determines whether a window supports the use of render targets
731
+ * Determine whether a renderer supports the use of render targets.
502
732
  *
503
- * \param renderer The renderer that will be checked
733
+ * \param renderer the renderer that will be checked
734
+ * \returns SDL_TRUE if supported or SDL_FALSE if not.
504
735
  *
505
- * \return SDL_TRUE if supported, SDL_FALSE if not.
736
+ * \since This function is available since SDL 2.0.0.
737
+ *
738
+ * \sa SDL_SetRenderTarget
506
739
  */
507
740
  extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *renderer);
508
741
 
509
742
  /**
510
- * \brief Set a texture as the current rendering target.
743
+ * Set a texture as the current rendering target.
511
744
  *
512
- * \param renderer The renderer.
513
- * \param texture The targeted texture, which must be created with the SDL_TEXTUREACCESS_TARGET flag, or NULL for the default render target
745
+ * Before using this function, you should check the
746
+ * `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see if
747
+ * render targets are supported.
514
748
  *
515
- * \return 0 on success, or -1 on error
749
+ * The default render target is the window for which the renderer was created.
750
+ * To stop rendering to a texture and render to the window again, call this
751
+ * function with a NULL `texture`.
752
+ *
753
+ * \param renderer the rendering context
754
+ * \param texture the targeted texture, which must be created with the
755
+ * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the
756
+ * window instead of a texture.
757
+ * \returns 0 on success or a negative error code on failure; call
758
+ * SDL_GetError() for more information.
759
+ *
760
+ * \since This function is available since SDL 2.0.0.
516
761
  *
517
- * \sa SDL_GetRenderTarget()
762
+ * \sa SDL_GetRenderTarget
518
763
  */
519
764
  extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer,
520
765
  SDL_Texture *texture);
521
766
 
522
767
  /**
523
- * \brief Get the current render target or NULL for the default render target.
768
+ * Get the current render target.
524
769
  *
525
- * \return The current render target
770
+ * The default render target is the window for which the renderer was created,
771
+ * and is reported a NULL here.
526
772
  *
527
- * \sa SDL_SetRenderTarget()
773
+ * \param renderer the rendering context
774
+ * \returns the current render target or NULL for the default render target.
775
+ *
776
+ * \since This function is available since SDL 2.0.0.
777
+ *
778
+ * \sa SDL_SetRenderTarget
528
779
  */
529
780
  extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer);
530
781
 
531
782
  /**
532
- * \brief Set device independent resolution for rendering
783
+ * Set a device independent resolution for rendering.
784
+ *
785
+ * This function uses the viewport and scaling functionality to allow a fixed
786
+ * logical resolution for rendering, regardless of the actual output
787
+ * resolution. If the actual output resolution doesn't have the same aspect
788
+ * ratio the output rendering will be centered within the output display.
533
789
  *
534
- * \param renderer The renderer for which resolution should be set.
535
- * \param w The width of the logical resolution
536
- * \param h The height of the logical resolution
790
+ * If the output display is a window, mouse and touch events in the window
791
+ * will be filtered and scaled so they seem to arrive within the logical
792
+ * resolution. The SDL_HINT_MOUSE_RELATIVE_SCALING hint controls whether
793
+ * relative motion events are also scaled.
537
794
  *
538
- * This function uses the viewport and scaling functionality to allow a fixed logical
539
- * resolution for rendering, regardless of the actual output resolution. If the actual
540
- * output resolution doesn't have the same aspect ratio the output rendering will be
541
- * centered within the output display.
795
+ * If this function results in scaling or subpixel drawing by the rendering
796
+ * backend, it will be handled using the appropriate quality hints.
542
797
  *
543
- * If the output display is a window, mouse events in the window will be filtered
544
- * and scaled so they seem to arrive within the logical resolution.
798
+ * \param renderer the renderer for which resolution should be set
799
+ * \param w the width of the logical resolution
800
+ * \param h the height of the logical resolution
801
+ * \returns 0 on success or a negative error code on failure; call
802
+ * SDL_GetError() for more information.
545
803
  *
546
- * \note If this function results in scaling or subpixel drawing by the
547
- * rendering backend, it will be handled using the appropriate
548
- * quality hints.
804
+ * \since This function is available since SDL 2.0.0.
549
805
  *
550
- * \sa SDL_RenderGetLogicalSize()
551
- * \sa SDL_RenderSetScale()
552
- * \sa SDL_RenderSetViewport()
806
+ * \sa SDL_RenderGetLogicalSize
553
807
  */
554
808
  extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, int w, int h);
555
809
 
556
810
  /**
557
- * \brief Get device independent resolution for rendering
811
+ * Get device independent resolution for rendering.
812
+ *
813
+ * This may return 0 for `w` and `h` if the SDL_Renderer has never had its
814
+ * logical size set by SDL_RenderSetLogicalSize() and never had a render
815
+ * target set.
816
+ *
817
+ * \param renderer a rendering context
818
+ * \param w an int to be filled with the width
819
+ * \param h an int to be filled with the height
558
820
  *
559
- * \param renderer The renderer from which resolution should be queried.
560
- * \param w A pointer filled with the width of the logical resolution
561
- * \param h A pointer filled with the height of the logical resolution
821
+ * \since This function is available since SDL 2.0.0.
562
822
  *
563
- * \sa SDL_RenderSetLogicalSize()
823
+ * \sa SDL_RenderSetLogicalSize
564
824
  */
565
825
  extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, int *w, int *h);
566
826
 
567
827
  /**
568
- * \brief Set whether to force integer scales for resolution-independent rendering
828
+ * Set whether to force integer scales for resolution-independent rendering.
569
829
  *
570
- * \param renderer The renderer for which integer scaling should be set.
571
- * \param enable Enable or disable integer scaling
830
+ * This function restricts the logical viewport to integer values - that is,
831
+ * when a resolution is between two multiples of a logical size, the viewport
832
+ * size is rounded down to the lower multiple.
572
833
  *
573
- * This function restricts the logical viewport to integer values - that is, when
574
- * a resolution is between two multiples of a logical size, the viewport size is
575
- * rounded down to the lower multiple.
834
+ * \param renderer the renderer for which integer scaling should be set
835
+ * \param enable enable or disable the integer scaling for rendering
836
+ * \returns 0 on success or a negative error code on failure; call
837
+ * SDL_GetError() for more information.
576
838
  *
577
- * \sa SDL_RenderSetLogicalSize()
839
+ * \since This function is available since SDL 2.0.5.
840
+ *
841
+ * \sa SDL_RenderGetIntegerScale
842
+ * \sa SDL_RenderSetLogicalSize
578
843
  */
579
844
  extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer,
580
845
  SDL_bool enable);
581
846
 
582
847
  /**
583
- * \brief Get whether integer scales are forced for resolution-independent rendering
848
+ * Get whether integer scales are forced for resolution-independent rendering.
849
+ *
850
+ * \param renderer the renderer from which integer scaling should be queried
851
+ * \returns SDL_TRUE if integer scales are forced or SDL_FALSE if not and on
852
+ * failure; call SDL_GetError() for more information.
584
853
  *
585
- * \param renderer The renderer from which integer scaling should be queried.
854
+ * \since This function is available since SDL 2.0.5.
586
855
  *
587
- * \sa SDL_RenderSetIntegerScale()
856
+ * \sa SDL_RenderSetIntegerScale
588
857
  */
589
858
  extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * renderer);
590
859
 
591
860
  /**
592
- * \brief Set the drawing area for rendering on the current target.
861
+ * Set the drawing area for rendering on the current target.
593
862
  *
594
- * \param renderer The renderer for which the drawing area should be set.
595
- * \param rect The rectangle representing the drawing area, or NULL to set the viewport to the entire target.
863
+ * When the window is resized, the viewport is reset to fill the entire new
864
+ * window size.
596
865
  *
597
- * The x,y of the viewport rect represents the origin for rendering.
866
+ * \param renderer the rendering context
867
+ * \param rect the SDL_Rect structure representing the drawing area, or NULL
868
+ * to set the viewport to the entire target
869
+ * \returns 0 on success or a negative error code on failure; call
870
+ * SDL_GetError() for more information.
598
871
  *
599
- * \return 0 on success, or -1 on error
872
+ * \since This function is available since SDL 2.0.0.
600
873
  *
601
- * \note If the window associated with the renderer is resized, the viewport is automatically reset.
602
- *
603
- * \sa SDL_RenderGetViewport()
604
- * \sa SDL_RenderSetLogicalSize()
874
+ * \sa SDL_RenderGetViewport
605
875
  */
606
876
  extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer,
607
877
  const SDL_Rect * rect);
608
878
 
609
879
  /**
610
- * \brief Get the drawing area for the current target.
880
+ * Get the drawing area for the current target.
881
+ *
882
+ * \param renderer the rendering context
883
+ * \param rect an SDL_Rect structure filled in with the current drawing area
611
884
  *
612
- * \sa SDL_RenderSetViewport()
885
+ * \since This function is available since SDL 2.0.0.
886
+ *
887
+ * \sa SDL_RenderSetViewport
613
888
  */
614
889
  extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer,
615
890
  SDL_Rect * rect);
616
891
 
617
892
  /**
618
- * \brief Set the clip rectangle for the current target.
893
+ * Set the clip rectangle for rendering on the specified target.
619
894
  *
620
- * \param renderer The renderer for which clip rectangle should be set.
621
- * \param rect A pointer to the rectangle to set as the clip rectangle,
622
- * relative to the viewport, or NULL to disable clipping.
895
+ * \param renderer the rendering context for which clip rectangle should be
896
+ * set
897
+ * \param rect an SDL_Rect structure representing the clip area, relative to
898
+ * the viewport, or NULL to disable clipping
899
+ * \returns 0 on success or a negative error code on failure; call
900
+ * SDL_GetError() for more information.
623
901
  *
624
- * \return 0 on success, or -1 on error
902
+ * \since This function is available since SDL 2.0.0.
625
903
  *
626
- * \sa SDL_RenderGetClipRect()
904
+ * \sa SDL_RenderGetClipRect
905
+ * \sa SDL_RenderIsClipEnabled
627
906
  */
628
907
  extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer,
629
908
  const SDL_Rect * rect);
630
909
 
631
910
  /**
632
- * \brief Get the clip rectangle for the current target.
911
+ * Get the clip rectangle for the current target.
912
+ *
913
+ * \param renderer the rendering context from which clip rectangle should be
914
+ * queried
915
+ * \param rect an SDL_Rect structure filled in with the current clipping area
916
+ * or an empty rectangle if clipping is disabled
633
917
  *
634
- * \param renderer The renderer from which clip rectangle should be queried.
635
- * \param rect A pointer filled in with the current clip rectangle, or
636
- * an empty rectangle if clipping is disabled.
918
+ * \since This function is available since SDL 2.0.0.
637
919
  *
638
- * \sa SDL_RenderSetClipRect()
920
+ * \sa SDL_RenderIsClipEnabled
921
+ * \sa SDL_RenderSetClipRect
639
922
  */
640
923
  extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer,
641
924
  SDL_Rect * rect);
642
925
 
643
926
  /**
644
- * \brief Get whether clipping is enabled on the given renderer.
927
+ * Get whether clipping is enabled on the given renderer.
928
+ *
929
+ * \param renderer the renderer from which clip state should be queried
930
+ * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call
931
+ * SDL_GetError() for more information.
645
932
  *
646
- * \param renderer The renderer from which clip state should be queried.
933
+ * \since This function is available since SDL 2.0.4.
647
934
  *
648
- * \sa SDL_RenderGetClipRect()
935
+ * \sa SDL_RenderGetClipRect
936
+ * \sa SDL_RenderSetClipRect
649
937
  */
650
938
  extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer);
651
939
 
652
940
 
653
941
  /**
654
- * \brief Set the drawing scale for rendering on the current target.
942
+ * Set the drawing scale for rendering on the current target.
655
943
  *
656
- * \param renderer The renderer for which the drawing scale should be set.
657
- * \param scaleX The horizontal scaling factor
658
- * \param scaleY The vertical scaling factor
944
+ * The drawing coordinates are scaled by the x/y scaling factors before they
945
+ * are used by the renderer. This allows resolution independent drawing with a
946
+ * single coordinate system.
659
947
  *
660
- * The drawing coordinates are scaled by the x/y scaling factors
661
- * before they are used by the renderer. This allows resolution
662
- * independent drawing with a single coordinate system.
948
+ * If this results in scaling or subpixel drawing by the rendering backend, it
949
+ * will be handled using the appropriate quality hints. For best results use
950
+ * integer scaling factors.
663
951
  *
664
- * \note If this results in scaling or subpixel drawing by the
665
- * rendering backend, it will be handled using the appropriate
666
- * quality hints. For best results use integer scaling factors.
952
+ * \param renderer a rendering context
953
+ * \param scaleX the horizontal scaling factor
954
+ * \param scaleY the vertical scaling factor
955
+ * \returns 0 on success or a negative error code on failure; call
956
+ * SDL_GetError() for more information.
667
957
  *
668
- * \sa SDL_RenderGetScale()
669
- * \sa SDL_RenderSetLogicalSize()
958
+ * \since This function is available since SDL 2.0.0.
959
+ *
960
+ * \sa SDL_RenderGetScale
961
+ * \sa SDL_RenderSetLogicalSize
670
962
  */
671
963
  extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer,
672
964
  float scaleX, float scaleY);
673
965
 
674
966
  /**
675
- * \brief Get the drawing scale for the current target.
967
+ * Get the drawing scale for the current target.
968
+ *
969
+ * \param renderer the renderer from which drawing scale should be queried
970
+ * \param scaleX a pointer filled in with the horizontal scaling factor
971
+ * \param scaleY a pointer filled in with the vertical scaling factor
676
972
  *
677
- * \param renderer The renderer from which drawing scale should be queried.
678
- * \param scaleX A pointer filled in with the horizontal scaling factor
679
- * \param scaleY A pointer filled in with the vertical scaling factor
973
+ * \since This function is available since SDL 2.0.0.
680
974
  *
681
- * \sa SDL_RenderSetScale()
975
+ * \sa SDL_RenderSetScale
682
976
  */
683
977
  extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer,
684
978
  float *scaleX, float *scaleY);
685
979
 
686
980
  /**
687
- * \brief Set the color used for drawing operations (Rect, Line and Clear).
688
- *
689
- * \param renderer The renderer for which drawing color should be set.
690
- * \param r The red value used to draw on the rendering target.
691
- * \param g The green value used to draw on the rendering target.
692
- * \param b The blue value used to draw on the rendering target.
693
- * \param a The alpha value used to draw on the rendering target, usually
694
- * ::SDL_ALPHA_OPAQUE (255).
695
- *
696
- * \return 0 on success, or -1 on error
981
+ * Get logical coordinates of point in renderer when given real coordinates of
982
+ * point in window.
983
+ *
984
+ * Logical coordinates will differ from real coordinates when render is scaled
985
+ * and logical renderer size set
986
+ *
987
+ * \param renderer the renderer from which the logical coordinates should be
988
+ * calcualted
989
+ * \param windowX the real X coordinate in the window
990
+ * \param windowY the real Y coordinate in the window
991
+ * \param logicalX the pointer filled with the logical x coordinate
992
+ * \param logicalY the pointer filled with the logical y coordinate
993
+ *
994
+ * \since This function is available since SDL 2.0.18.
995
+ *
996
+ * \sa SDL_RenderGetScale
997
+ * \sa SDL_RenderSetScale
998
+ * \sa SDL_RenderGetLogicalSize
999
+ * \sa SDL_RenderSetLogicalSize
1000
+ */
1001
+ extern DECLSPEC void SDLCALL SDL_RenderWindowToLogical(SDL_Renderer * renderer,
1002
+ int windowX, int windowY,
1003
+ float *logicalX, float *logicalY);
1004
+
1005
+ /**
1006
+ * Get real coordinates of point in window when given logical coordinates of point in renderer.
1007
+ * Logical coordinates will differ from real coordinates when render is scaled and logical renderer size set
1008
+ *
1009
+ * \param renderer the renderer from which the window coordinates should be calculated
1010
+ * \param logicalX the logical x coordinate
1011
+ * \param logicalY the logical y coordinate
1012
+ * \param windowX the pointer filled with the real X coordinate in the window
1013
+ * \param windowY the pointer filled with the real Y coordinate in the window
1014
+
1015
+ *
1016
+ * \since This function is available since SDL 2.0.18.
1017
+ *
1018
+ * \sa SDL_RenderGetScale
1019
+ * \sa SDL_RenderSetScale
1020
+ * \sa SDL_RenderGetLogicalSize
1021
+ * \sa SDL_RenderSetLogicalSize
1022
+ */
1023
+ extern DECLSPEC void SDLCALL SDL_RenderLogicalToWindow(SDL_Renderer * renderer,
1024
+ float logicalX, float logicalY,
1025
+ int *windowX, int *windowY);
1026
+
1027
+ /**
1028
+ * Set the color used for drawing operations (Rect, Line and Clear).
1029
+ *
1030
+ * Set the color for drawing or filling rectangles, lines, and points, and for
1031
+ * SDL_RenderClear().
1032
+ *
1033
+ * \param renderer the rendering context
1034
+ * \param r the red value used to draw on the rendering target
1035
+ * \param g the green value used to draw on the rendering target
1036
+ * \param b the blue value used to draw on the rendering target
1037
+ * \param a the alpha value used to draw on the rendering target; usually
1038
+ * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to
1039
+ * specify how the alpha channel is used
1040
+ * \returns 0 on success or a negative error code on failure; call
1041
+ * SDL_GetError() for more information.
1042
+ *
1043
+ * \since This function is available since SDL 2.0.0.
1044
+ *
1045
+ * \sa SDL_GetRenderDrawColor
1046
+ * \sa SDL_RenderClear
1047
+ * \sa SDL_RenderDrawLine
1048
+ * \sa SDL_RenderDrawLines
1049
+ * \sa SDL_RenderDrawPoint
1050
+ * \sa SDL_RenderDrawPoints
1051
+ * \sa SDL_RenderDrawRect
1052
+ * \sa SDL_RenderDrawRects
1053
+ * \sa SDL_RenderFillRect
1054
+ * \sa SDL_RenderFillRects
697
1055
  */
698
1056
  extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer,
699
1057
  Uint8 r, Uint8 g, Uint8 b,
700
1058
  Uint8 a);
701
1059
 
702
1060
  /**
703
- * \brief Get the color used for drawing operations (Rect, Line and Clear).
1061
+ * Get the color used for drawing operations (Rect, Line and Clear).
1062
+ *
1063
+ * \param renderer the rendering context
1064
+ * \param r a pointer filled in with the red value used to draw on the
1065
+ * rendering target
1066
+ * \param g a pointer filled in with the green value used to draw on the
1067
+ * rendering target
1068
+ * \param b a pointer filled in with the blue value used to draw on the
1069
+ * rendering target
1070
+ * \param a a pointer filled in with the alpha value used to draw on the
1071
+ * rendering target; usually `SDL_ALPHA_OPAQUE` (255)
1072
+ * \returns 0 on success or a negative error code on failure; call
1073
+ * SDL_GetError() for more information.
704
1074
  *
705
- * \param renderer The renderer from which drawing color should be queried.
706
- * \param r A pointer to the red value used to draw on the rendering target.
707
- * \param g A pointer to the green value used to draw on the rendering target.
708
- * \param b A pointer to the blue value used to draw on the rendering target.
709
- * \param a A pointer to the alpha value used to draw on the rendering target,
710
- * usually ::SDL_ALPHA_OPAQUE (255).
1075
+ * \since This function is available since SDL 2.0.0.
711
1076
  *
712
- * \return 0 on success, or -1 on error
1077
+ * \sa SDL_SetRenderDrawColor
713
1078
  */
714
1079
  extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer,
715
1080
  Uint8 * r, Uint8 * g, Uint8 * b,
716
1081
  Uint8 * a);
717
1082
 
718
1083
  /**
719
- * \brief Set the blend mode used for drawing operations (Fill and Line).
1084
+ * Set the blend mode used for drawing operations (Fill and Line).
720
1085
  *
721
- * \param renderer The renderer for which blend mode should be set.
722
- * \param blendMode ::SDL_BlendMode to use for blending.
1086
+ * If the blend mode is not supported, the closest supported mode is chosen.
723
1087
  *
724
- * \return 0 on success, or -1 on error
1088
+ * \param renderer the rendering context
1089
+ * \param blendMode the SDL_BlendMode to use for blending
1090
+ * \returns 0 on success or a negative error code on failure; call
1091
+ * SDL_GetError() for more information.
725
1092
  *
726
- * \note If the blend mode is not supported, the closest supported mode is
727
- * chosen.
1093
+ * \since This function is available since SDL 2.0.0.
728
1094
  *
729
- * \sa SDL_GetRenderDrawBlendMode()
1095
+ * \sa SDL_GetRenderDrawBlendMode
1096
+ * \sa SDL_RenderDrawLine
1097
+ * \sa SDL_RenderDrawLines
1098
+ * \sa SDL_RenderDrawPoint
1099
+ * \sa SDL_RenderDrawPoints
1100
+ * \sa SDL_RenderDrawRect
1101
+ * \sa SDL_RenderDrawRects
1102
+ * \sa SDL_RenderFillRect
1103
+ * \sa SDL_RenderFillRects
730
1104
  */
731
1105
  extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer,
732
1106
  SDL_BlendMode blendMode);
733
1107
 
734
1108
  /**
735
- * \brief Get the blend mode used for drawing operations.
1109
+ * Get the blend mode used for drawing operations.
736
1110
  *
737
- * \param renderer The renderer from which blend mode should be queried.
738
- * \param blendMode A pointer filled in with the current blend mode.
1111
+ * \param renderer the rendering context
1112
+ * \param blendMode a pointer filled in with the current SDL_BlendMode
1113
+ * \returns 0 on success or a negative error code on failure; call
1114
+ * SDL_GetError() for more information.
739
1115
  *
740
- * \return 0 on success, or -1 on error
1116
+ * \since This function is available since SDL 2.0.0.
741
1117
  *
742
- * \sa SDL_SetRenderDrawBlendMode()
1118
+ * \sa SDL_SetRenderDrawBlendMode
743
1119
  */
744
1120
  extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer,
745
1121
  SDL_BlendMode *blendMode);
746
1122
 
747
1123
  /**
748
- * \brief Clear the current rendering target with the drawing color
1124
+ * Clear the current rendering target with the drawing color.
1125
+ *
1126
+ * This function clears the entire rendering target, ignoring the viewport and
1127
+ * the clip rectangle.
1128
+ *
1129
+ * \param renderer the rendering context
1130
+ * \returns 0 on success or a negative error code on failure; call
1131
+ * SDL_GetError() for more information.
749
1132
  *
750
- * This function clears the entire rendering target, ignoring the viewport and
751
- * the clip rectangle.
1133
+ * \since This function is available since SDL 2.0.0.
752
1134
  *
753
- * \return 0 on success, or -1 on error
1135
+ * \sa SDL_SetRenderDrawColor
754
1136
  */
755
1137
  extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer);
756
1138
 
757
1139
  /**
758
- * \brief Draw a point on the current rendering target.
1140
+ * Draw a point on the current rendering target.
759
1141
  *
760
- * \param renderer The renderer which should draw a point.
761
- * \param x The x coordinate of the point.
762
- * \param y The y coordinate of the point.
1142
+ * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple,
1143
+ * use SDL_RenderDrawPoints() instead.
763
1144
  *
764
- * \return 0 on success, or -1 on error
1145
+ * \param renderer the rendering context
1146
+ * \param x the x coordinate of the point
1147
+ * \param y the y coordinate of the point
1148
+ * \returns 0 on success or a negative error code on failure; call
1149
+ * SDL_GetError() for more information.
1150
+ *
1151
+ * \since This function is available since SDL 2.0.0.
1152
+ *
1153
+ * \sa SDL_RenderDrawLine
1154
+ * \sa SDL_RenderDrawLines
1155
+ * \sa SDL_RenderDrawPoints
1156
+ * \sa SDL_RenderDrawRect
1157
+ * \sa SDL_RenderDrawRects
1158
+ * \sa SDL_RenderFillRect
1159
+ * \sa SDL_RenderFillRects
1160
+ * \sa SDL_RenderPresent
1161
+ * \sa SDL_SetRenderDrawBlendMode
1162
+ * \sa SDL_SetRenderDrawColor
765
1163
  */
766
1164
  extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer,
767
1165
  int x, int y);
768
1166
 
769
1167
  /**
770
- * \brief Draw multiple points on the current rendering target.
1168
+ * Draw multiple points on the current rendering target.
1169
+ *
1170
+ * \param renderer the rendering context
1171
+ * \param points an array of SDL_Point structures that represent the points to
1172
+ * draw
1173
+ * \param count the number of points to draw
1174
+ * \returns 0 on success or a negative error code on failure; call
1175
+ * SDL_GetError() for more information.
771
1176
  *
772
- * \param renderer The renderer which should draw multiple points.
773
- * \param points The points to draw
774
- * \param count The number of points to draw
1177
+ * \since This function is available since SDL 2.0.0.
775
1178
  *
776
- * \return 0 on success, or -1 on error
1179
+ * \sa SDL_RenderDrawLine
1180
+ * \sa SDL_RenderDrawLines
1181
+ * \sa SDL_RenderDrawPoint
1182
+ * \sa SDL_RenderDrawRect
1183
+ * \sa SDL_RenderDrawRects
1184
+ * \sa SDL_RenderFillRect
1185
+ * \sa SDL_RenderFillRects
1186
+ * \sa SDL_RenderPresent
1187
+ * \sa SDL_SetRenderDrawBlendMode
1188
+ * \sa SDL_SetRenderDrawColor
777
1189
  */
778
1190
  extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer,
779
1191
  const SDL_Point * points,
780
1192
  int count);
781
1193
 
782
1194
  /**
783
- * \brief Draw a line on the current rendering target.
1195
+ * Draw a line on the current rendering target.
1196
+ *
1197
+ * SDL_RenderDrawLine() draws the line to include both end points. If you want
1198
+ * to draw multiple, connecting lines use SDL_RenderDrawLines() instead.
1199
+ *
1200
+ * \param renderer the rendering context
1201
+ * \param x1 the x coordinate of the start point
1202
+ * \param y1 the y coordinate of the start point
1203
+ * \param x2 the x coordinate of the end point
1204
+ * \param y2 the y coordinate of the end point
1205
+ * \returns 0 on success or a negative error code on failure; call
1206
+ * SDL_GetError() for more information.
784
1207
  *
785
- * \param renderer The renderer which should draw a line.
786
- * \param x1 The x coordinate of the start point.
787
- * \param y1 The y coordinate of the start point.
788
- * \param x2 The x coordinate of the end point.
789
- * \param y2 The y coordinate of the end point.
1208
+ * \since This function is available since SDL 2.0.0.
790
1209
  *
791
- * \return 0 on success, or -1 on error
1210
+ * \sa SDL_RenderDrawLines
1211
+ * \sa SDL_RenderDrawPoint
1212
+ * \sa SDL_RenderDrawPoints
1213
+ * \sa SDL_RenderDrawRect
1214
+ * \sa SDL_RenderDrawRects
1215
+ * \sa SDL_RenderFillRect
1216
+ * \sa SDL_RenderFillRects
1217
+ * \sa SDL_RenderPresent
1218
+ * \sa SDL_SetRenderDrawBlendMode
1219
+ * \sa SDL_SetRenderDrawColor
792
1220
  */
793
1221
  extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer,
794
1222
  int x1, int y1, int x2, int y2);
795
1223
 
796
1224
  /**
797
- * \brief Draw a series of connected lines on the current rendering target.
1225
+ * Draw a series of connected lines on the current rendering target.
798
1226
  *
799
- * \param renderer The renderer which should draw multiple lines.
800
- * \param points The points along the lines
801
- * \param count The number of points, drawing count-1 lines
1227
+ * \param renderer the rendering context
1228
+ * \param points an array of SDL_Point structures representing points along
1229
+ * the lines
1230
+ * \param count the number of points, drawing count-1 lines
1231
+ * \returns 0 on success or a negative error code on failure; call
1232
+ * SDL_GetError() for more information.
802
1233
  *
803
- * \return 0 on success, or -1 on error
1234
+ * \since This function is available since SDL 2.0.0.
1235
+ *
1236
+ * \sa SDL_RenderDrawLine
1237
+ * \sa SDL_RenderDrawPoint
1238
+ * \sa SDL_RenderDrawPoints
1239
+ * \sa SDL_RenderDrawRect
1240
+ * \sa SDL_RenderDrawRects
1241
+ * \sa SDL_RenderFillRect
1242
+ * \sa SDL_RenderFillRects
1243
+ * \sa SDL_RenderPresent
1244
+ * \sa SDL_SetRenderDrawBlendMode
1245
+ * \sa SDL_SetRenderDrawColor
804
1246
  */
805
1247
  extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer,
806
1248
  const SDL_Point * points,
807
1249
  int count);
808
1250
 
809
1251
  /**
810
- * \brief Draw a rectangle on the current rendering target.
1252
+ * Draw a rectangle on the current rendering target.
1253
+ *
1254
+ * \param renderer the rendering context
1255
+ * \param rect an SDL_Rect structure representing the rectangle to draw, or
1256
+ * NULL to outline the entire rendering target
1257
+ * \returns 0 on success or a negative error code on failure; call
1258
+ * SDL_GetError() for more information.
811
1259
  *
812
- * \param renderer The renderer which should draw a rectangle.
813
- * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
1260
+ * \since This function is available since SDL 2.0.0.
814
1261
  *
815
- * \return 0 on success, or -1 on error
1262
+ * \sa SDL_RenderDrawLine
1263
+ * \sa SDL_RenderDrawLines
1264
+ * \sa SDL_RenderDrawPoint
1265
+ * \sa SDL_RenderDrawPoints
1266
+ * \sa SDL_RenderDrawRects
1267
+ * \sa SDL_RenderFillRect
1268
+ * \sa SDL_RenderFillRects
1269
+ * \sa SDL_RenderPresent
1270
+ * \sa SDL_SetRenderDrawBlendMode
1271
+ * \sa SDL_SetRenderDrawColor
816
1272
  */
817
1273
  extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer,
818
1274
  const SDL_Rect * rect);
819
1275
 
820
1276
  /**
821
- * \brief Draw some number of rectangles on the current rendering target.
1277
+ * Draw some number of rectangles on the current rendering target.
822
1278
  *
823
- * \param renderer The renderer which should draw multiple rectangles.
824
- * \param rects A pointer to an array of destination rectangles.
825
- * \param count The number of rectangles.
1279
+ * \param renderer the rendering context
1280
+ * \param rects an array of SDL_Rect structures representing the rectangles to
1281
+ * be drawn
1282
+ * \param count the number of rectangles
1283
+ * \returns 0 on success or a negative error code on failure; call
1284
+ * SDL_GetError() for more information.
826
1285
  *
827
- * \return 0 on success, or -1 on error
1286
+ * \since This function is available since SDL 2.0.0.
1287
+ *
1288
+ * \sa SDL_RenderDrawLine
1289
+ * \sa SDL_RenderDrawLines
1290
+ * \sa SDL_RenderDrawPoint
1291
+ * \sa SDL_RenderDrawPoints
1292
+ * \sa SDL_RenderDrawRect
1293
+ * \sa SDL_RenderFillRect
1294
+ * \sa SDL_RenderFillRects
1295
+ * \sa SDL_RenderPresent
1296
+ * \sa SDL_SetRenderDrawBlendMode
1297
+ * \sa SDL_SetRenderDrawColor
828
1298
  */
829
1299
  extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer,
830
1300
  const SDL_Rect * rects,
831
1301
  int count);
832
1302
 
833
1303
  /**
834
- * \brief Fill a rectangle on the current rendering target with the drawing color.
1304
+ * Fill a rectangle on the current rendering target with the drawing color.
1305
+ *
1306
+ * The current drawing color is set by SDL_SetRenderDrawColor(), and the
1307
+ * color's alpha value is ignored unless blending is enabled with the
1308
+ * appropriate call to SDL_SetRenderDrawBlendMode().
835
1309
  *
836
- * \param renderer The renderer which should fill a rectangle.
837
- * \param rect A pointer to the destination rectangle, or NULL for the entire
838
- * rendering target.
1310
+ * \param renderer the rendering context
1311
+ * \param rect the SDL_Rect structure representing the rectangle to fill, or
1312
+ * NULL for the entire rendering target
1313
+ * \returns 0 on success or a negative error code on failure; call
1314
+ * SDL_GetError() for more information.
839
1315
  *
840
- * \return 0 on success, or -1 on error
1316
+ * \since This function is available since SDL 2.0.0.
1317
+ *
1318
+ * \sa SDL_RenderDrawLine
1319
+ * \sa SDL_RenderDrawLines
1320
+ * \sa SDL_RenderDrawPoint
1321
+ * \sa SDL_RenderDrawPoints
1322
+ * \sa SDL_RenderDrawRect
1323
+ * \sa SDL_RenderDrawRects
1324
+ * \sa SDL_RenderFillRects
1325
+ * \sa SDL_RenderPresent
1326
+ * \sa SDL_SetRenderDrawBlendMode
1327
+ * \sa SDL_SetRenderDrawColor
841
1328
  */
842
1329
  extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer,
843
1330
  const SDL_Rect * rect);
844
1331
 
845
1332
  /**
846
- * \brief Fill some number of rectangles on the current rendering target with the drawing color.
1333
+ * Fill some number of rectangles on the current rendering target with the
1334
+ * drawing color.
1335
+ *
1336
+ * \param renderer the rendering context
1337
+ * \param rects an array of SDL_Rect structures representing the rectangles to
1338
+ * be filled
1339
+ * \param count the number of rectangles
1340
+ * \returns 0 on success or a negative error code on failure; call
1341
+ * SDL_GetError() for more information.
847
1342
  *
848
- * \param renderer The renderer which should fill multiple rectangles.
849
- * \param rects A pointer to an array of destination rectangles.
850
- * \param count The number of rectangles.
1343
+ * \since This function is available since SDL 2.0.0.
851
1344
  *
852
- * \return 0 on success, or -1 on error
1345
+ * \sa SDL_RenderDrawLine
1346
+ * \sa SDL_RenderDrawLines
1347
+ * \sa SDL_RenderDrawPoint
1348
+ * \sa SDL_RenderDrawPoints
1349
+ * \sa SDL_RenderDrawRect
1350
+ * \sa SDL_RenderDrawRects
1351
+ * \sa SDL_RenderFillRect
1352
+ * \sa SDL_RenderPresent
853
1353
  */
854
1354
  extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer,
855
1355
  const SDL_Rect * rects,
856
1356
  int count);
857
1357
 
858
1358
  /**
859
- * \brief Copy a portion of the texture to the current rendering target.
1359
+ * Copy a portion of the texture to the current rendering target.
1360
+ *
1361
+ * The texture is blended with the destination based on its blend mode set
1362
+ * with SDL_SetTextureBlendMode().
1363
+ *
1364
+ * The texture color is affected based on its color modulation set by
1365
+ * SDL_SetTextureColorMod().
1366
+ *
1367
+ * The texture alpha is affected based on its alpha modulation set by
1368
+ * SDL_SetTextureAlphaMod().
860
1369
  *
861
- * \param renderer The renderer which should copy parts of a texture.
862
- * \param texture The source texture.
863
- * \param srcrect A pointer to the source rectangle, or NULL for the entire
864
- * texture.
865
- * \param dstrect A pointer to the destination rectangle, or NULL for the
866
- * entire rendering target.
1370
+ * \param renderer the rendering context
1371
+ * \param texture the source texture
1372
+ * \param srcrect the source SDL_Rect structure or NULL for the entire texture
1373
+ * \param dstrect the destination SDL_Rect structure or NULL for the entire
1374
+ * rendering target; the texture will be stretched to fill the
1375
+ * given rectangle
1376
+ * \returns 0 on success or a negative error code on failure; call
1377
+ * SDL_GetError() for more information.
867
1378
  *
868
- * \return 0 on success, or -1 on error
1379
+ * \since This function is available since SDL 2.0.0.
1380
+ *
1381
+ * \sa SDL_RenderCopyEx
1382
+ * \sa SDL_SetTextureAlphaMod
1383
+ * \sa SDL_SetTextureBlendMode
1384
+ * \sa SDL_SetTextureColorMod
869
1385
  */
870
1386
  extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
871
1387
  SDL_Texture * texture,
@@ -873,19 +1389,43 @@ extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
873
1389
  const SDL_Rect * dstrect);
874
1390
 
875
1391
  /**
876
- * \brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center
1392
+ * Copy a portion of the texture to the current rendering, with optional
1393
+ * rotation and flipping.
1394
+ *
1395
+ * Copy a portion of the texture to the current rendering target, optionally
1396
+ * rotating it by angle around the given center and also flipping it
1397
+ * top-bottom and/or left-right.
1398
+ *
1399
+ * The texture is blended with the destination based on its blend mode set
1400
+ * with SDL_SetTextureBlendMode().
1401
+ *
1402
+ * The texture color is affected based on its color modulation set by
1403
+ * SDL_SetTextureColorMod().
1404
+ *
1405
+ * The texture alpha is affected based on its alpha modulation set by
1406
+ * SDL_SetTextureAlphaMod().
877
1407
  *
878
- * \param renderer The renderer which should copy parts of a texture.
879
- * \param texture The source texture.
880
- * \param srcrect A pointer to the source rectangle, or NULL for the entire
881
- * texture.
882
- * \param dstrect A pointer to the destination rectangle, or NULL for the
883
- * entire rendering target.
884
- * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
885
- * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
886
- * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
1408
+ * \param renderer the rendering context
1409
+ * \param texture the source texture
1410
+ * \param srcrect the source SDL_Rect structure or NULL for the entire texture
1411
+ * \param dstrect the destination SDL_Rect structure or NULL for the entire
1412
+ * rendering target
1413
+ * \param angle an angle in degrees that indicates the rotation that will be
1414
+ * applied to dstrect, rotating it in a clockwise direction
1415
+ * \param center a pointer to a point indicating the point around which
1416
+ * dstrect will be rotated (if NULL, rotation will be done
1417
+ * around `dstrect.w / 2`, `dstrect.h / 2`)
1418
+ * \param flip a SDL_RendererFlip value stating which flipping actions should
1419
+ * be performed on the texture
1420
+ * \returns 0 on success or a negative error code on failure; call
1421
+ * SDL_GetError() for more information.
887
1422
  *
888
- * \return 0 on success, or -1 on error
1423
+ * \since This function is available since SDL 2.0.0.
1424
+ *
1425
+ * \sa SDL_RenderCopy
1426
+ * \sa SDL_SetTextureAlphaMod
1427
+ * \sa SDL_SetTextureBlendMode
1428
+ * \sa SDL_SetTextureColorMod
889
1429
  */
890
1430
  extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer,
891
1431
  SDL_Texture * texture,
@@ -897,117 +1437,132 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer,
897
1437
 
898
1438
 
899
1439
  /**
900
- * \brief Draw a point on the current rendering target.
1440
+ * Draw a point on the current rendering target at subpixel precision.
901
1441
  *
902
- * \param renderer The renderer which should draw a point.
903
- * \param x The x coordinate of the point.
904
- * \param y The y coordinate of the point.
1442
+ * \param renderer The renderer which should draw a point.
1443
+ * \param x The x coordinate of the point.
1444
+ * \param y The y coordinate of the point.
1445
+ * \return 0 on success, or -1 on error
905
1446
  *
906
- * \return 0 on success, or -1 on error
1447
+ * \since This function is available since SDL 2.0.10.
907
1448
  */
908
1449
  extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer,
909
1450
  float x, float y);
910
1451
 
911
1452
  /**
912
- * \brief Draw multiple points on the current rendering target.
1453
+ * Draw multiple points on the current rendering target at subpixel precision.
913
1454
  *
914
- * \param renderer The renderer which should draw multiple points.
915
- * \param points The points to draw
916
- * \param count The number of points to draw
1455
+ * \param renderer The renderer which should draw multiple points.
1456
+ * \param points The points to draw
1457
+ * \param count The number of points to draw
1458
+ * \return 0 on success, or -1 on error
917
1459
  *
918
- * \return 0 on success, or -1 on error
1460
+ * \since This function is available since SDL 2.0.10.
919
1461
  */
920
1462
  extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer,
921
1463
  const SDL_FPoint * points,
922
1464
  int count);
923
1465
 
924
1466
  /**
925
- * \brief Draw a line on the current rendering target.
1467
+ * Draw a line on the current rendering target at subpixel precision.
926
1468
  *
927
- * \param renderer The renderer which should draw a line.
928
- * \param x1 The x coordinate of the start point.
929
- * \param y1 The y coordinate of the start point.
930
- * \param x2 The x coordinate of the end point.
931
- * \param y2 The y coordinate of the end point.
1469
+ * \param renderer The renderer which should draw a line.
1470
+ * \param x1 The x coordinate of the start point.
1471
+ * \param y1 The y coordinate of the start point.
1472
+ * \param x2 The x coordinate of the end point.
1473
+ * \param y2 The y coordinate of the end point.
1474
+ * \return 0 on success, or -1 on error
932
1475
  *
933
- * \return 0 on success, or -1 on error
1476
+ * \since This function is available since SDL 2.0.10.
934
1477
  */
935
1478
  extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer,
936
1479
  float x1, float y1, float x2, float y2);
937
1480
 
938
1481
  /**
939
- * \brief Draw a series of connected lines on the current rendering target.
1482
+ * Draw a series of connected lines on the current rendering target at
1483
+ * subpixel precision.
940
1484
  *
941
- * \param renderer The renderer which should draw multiple lines.
942
- * \param points The points along the lines
943
- * \param count The number of points, drawing count-1 lines
1485
+ * \param renderer The renderer which should draw multiple lines.
1486
+ * \param points The points along the lines
1487
+ * \param count The number of points, drawing count-1 lines
1488
+ * \return 0 on success, or -1 on error
944
1489
  *
945
- * \return 0 on success, or -1 on error
1490
+ * \since This function is available since SDL 2.0.10.
946
1491
  */
947
1492
  extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer,
948
- const SDL_FPoint * points,
949
- int count);
1493
+ const SDL_FPoint * points,
1494
+ int count);
950
1495
 
951
1496
  /**
952
- * \brief Draw a rectangle on the current rendering target.
1497
+ * Draw a rectangle on the current rendering target at subpixel precision.
953
1498
  *
954
- * \param renderer The renderer which should draw a rectangle.
955
- * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
1499
+ * \param renderer The renderer which should draw a rectangle.
1500
+ * \param rect A pointer to the destination rectangle, or NULL to outline the
1501
+ * entire rendering target.
1502
+ * \return 0 on success, or -1 on error
956
1503
  *
957
- * \return 0 on success, or -1 on error
1504
+ * \since This function is available since SDL 2.0.10.
958
1505
  */
959
1506
  extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer,
960
- const SDL_FRect * rect);
1507
+ const SDL_FRect * rect);
961
1508
 
962
1509
  /**
963
- * \brief Draw some number of rectangles on the current rendering target.
1510
+ * Draw some number of rectangles on the current rendering target at subpixel
1511
+ * precision.
964
1512
  *
965
- * \param renderer The renderer which should draw multiple rectangles.
966
- * \param rects A pointer to an array of destination rectangles.
967
- * \param count The number of rectangles.
1513
+ * \param renderer The renderer which should draw multiple rectangles.
1514
+ * \param rects A pointer to an array of destination rectangles.
1515
+ * \param count The number of rectangles.
1516
+ * \return 0 on success, or -1 on error
968
1517
  *
969
- * \return 0 on success, or -1 on error
1518
+ * \since This function is available since SDL 2.0.10.
970
1519
  */
971
1520
  extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer,
972
1521
  const SDL_FRect * rects,
973
1522
  int count);
974
1523
 
975
1524
  /**
976
- * \brief Fill a rectangle on the current rendering target with the drawing color.
1525
+ * Fill a rectangle on the current rendering target with the drawing color at
1526
+ * subpixel precision.
977
1527
  *
978
- * \param renderer The renderer which should fill a rectangle.
979
- * \param rect A pointer to the destination rectangle, or NULL for the entire
980
- * rendering target.
1528
+ * \param renderer The renderer which should fill a rectangle.
1529
+ * \param rect A pointer to the destination rectangle, or NULL for the entire
1530
+ * rendering target.
1531
+ * \return 0 on success, or -1 on error
981
1532
  *
982
- * \return 0 on success, or -1 on error
1533
+ * \since This function is available since SDL 2.0.10.
983
1534
  */
984
1535
  extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer,
985
1536
  const SDL_FRect * rect);
986
1537
 
987
1538
  /**
988
- * \brief Fill some number of rectangles on the current rendering target with the drawing color.
1539
+ * Fill some number of rectangles on the current rendering target with the
1540
+ * drawing color at subpixel precision.
989
1541
  *
990
- * \param renderer The renderer which should fill multiple rectangles.
991
- * \param rects A pointer to an array of destination rectangles.
992
- * \param count The number of rectangles.
1542
+ * \param renderer The renderer which should fill multiple rectangles.
1543
+ * \param rects A pointer to an array of destination rectangles.
1544
+ * \param count The number of rectangles.
1545
+ * \return 0 on success, or -1 on error
993
1546
  *
994
- * \return 0 on success, or -1 on error
1547
+ * \since This function is available since SDL 2.0.10.
995
1548
  */
996
1549
  extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer,
997
1550
  const SDL_FRect * rects,
998
1551
  int count);
999
1552
 
1000
1553
  /**
1001
- * \brief Copy a portion of the texture to the current rendering target.
1554
+ * Copy a portion of the texture to the current rendering target at subpixel
1555
+ * precision.
1002
1556
  *
1003
- * \param renderer The renderer which should copy parts of a texture.
1004
- * \param texture The source texture.
1005
- * \param srcrect A pointer to the source rectangle, or NULL for the entire
1006
- * texture.
1007
- * \param dstrect A pointer to the destination rectangle, or NULL for the
1008
- * entire rendering target.
1557
+ * \param renderer The renderer which should copy parts of a texture.
1558
+ * \param texture The source texture.
1559
+ * \param srcrect A pointer to the source rectangle, or NULL for the entire
1560
+ * texture.
1561
+ * \param dstrect A pointer to the destination rectangle, or NULL for the
1562
+ * entire rendering target.
1563
+ * \return 0 on success, or -1 on error
1009
1564
  *
1010
- * \return 0 on success, or -1 on error
1565
+ * \since This function is available since SDL 2.0.10.
1011
1566
  */
1012
1567
  extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
1013
1568
  SDL_Texture * texture,
@@ -1015,19 +1570,25 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
1015
1570
  const SDL_FRect * dstrect);
1016
1571
 
1017
1572
  /**
1018
- * \brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center
1019
- *
1020
- * \param renderer The renderer which should copy parts of a texture.
1021
- * \param texture The source texture.
1022
- * \param srcrect A pointer to the source rectangle, or NULL for the entire
1023
- * texture.
1024
- * \param dstrect A pointer to the destination rectangle, or NULL for the
1025
- * entire rendering target.
1026
- * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
1027
- * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
1028
- * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
1573
+ * Copy a portion of the source texture to the current rendering target, with
1574
+ * rotation and flipping, at subpixel precision.
1575
+ *
1576
+ * \param renderer The renderer which should copy parts of a texture.
1577
+ * \param texture The source texture.
1578
+ * \param srcrect A pointer to the source rectangle, or NULL for the entire
1579
+ * texture.
1580
+ * \param dstrect A pointer to the destination rectangle, or NULL for the
1581
+ * entire rendering target.
1582
+ * \param angle An angle in degrees that indicates the rotation that will be
1583
+ * applied to dstrect, rotating it in a clockwise direction
1584
+ * \param center A pointer to a point indicating the point around which
1585
+ * dstrect will be rotated (if NULL, rotation will be done
1586
+ * around dstrect.w/2, dstrect.h/2).
1587
+ * \param flip An SDL_RendererFlip value stating which flipping actions should
1588
+ * be performed on the texture
1589
+ * \return 0 on success, or -1 on error
1029
1590
  *
1030
- * \return 0 on success, or -1 on error
1591
+ * \since This function is available since SDL 2.0.10.
1031
1592
  */
1032
1593
  extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
1033
1594
  SDL_Texture * texture,
@@ -1038,19 +1599,85 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
1038
1599
  const SDL_RendererFlip flip);
1039
1600
 
1040
1601
  /**
1041
- * \brief Read pixels from the current rendering target.
1042
- *
1043
- * \param renderer The renderer from which pixels should be read.
1044
- * \param rect A pointer to the rectangle to read, or NULL for the entire
1045
- * render target.
1046
- * \param format The desired format of the pixel data, or 0 to use the format
1047
- * of the rendering target
1048
- * \param pixels A pointer to be filled in with the pixel data
1049
- * \param pitch The pitch of the pixels parameter.
1050
- *
1051
- * \return 0 on success, or -1 if pixel reading is not supported.
1052
- *
1053
- * \warning This is a very slow operation, and should not be used frequently.
1602
+ * Render a list of triangles, optionally using a texture and indices into the
1603
+ * vertex array Color and alpha modulation is done per vertex
1604
+ * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored).
1605
+ *
1606
+ * \param texture (optional) The SDL texture to use.
1607
+ * \param vertices Vertices.
1608
+ * \param num_vertices Number of vertices.
1609
+ * \param indices (optional) An array of integer indices into the 'vertices'
1610
+ * array, if NULL all vertices will be rendered in sequential
1611
+ * order.
1612
+ * \param num_indices Number of indices.
1613
+ * \return 0 on success, or -1 if the operation is not supported
1614
+ *
1615
+ * \since This function is available since SDL 2.0.18.
1616
+ *
1617
+ * \sa SDL_RenderGeometryRaw
1618
+ * \sa SDL_Vertex
1619
+ */
1620
+ extern DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer,
1621
+ SDL_Texture *texture,
1622
+ const SDL_Vertex *vertices, int num_vertices,
1623
+ const int *indices, int num_indices);
1624
+
1625
+ /**
1626
+ * Render a list of triangles, optionally using a texture and indices into the
1627
+ * vertex arrays Color and alpha modulation is done per vertex
1628
+ * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored).
1629
+ *
1630
+ * \param texture (optional) The SDL texture to use.
1631
+ * \param xy Vertex positions
1632
+ * \param xy_stride Byte size to move from one element to the next element
1633
+ * \param color Vertex colors (as SDL_Color)
1634
+ * \param color_stride Byte size to move from one element to the next element
1635
+ * \param uv Vertex normalized texture coordinates
1636
+ * \param uv_stride Byte size to move from one element to the next element
1637
+ * \param num_vertices Number of vertices.
1638
+ * \param indices (optional) An array of indices into the 'vertices' arrays,
1639
+ * if NULL all vertices will be rendered in sequential order.
1640
+ * \param num_indices Number of indices.
1641
+ * \param size_indices Index size: 1 (byte), 2 (short), 4 (int)
1642
+ * \return 0 on success, or -1 if the operation is not supported
1643
+ *
1644
+ * \since This function is available since SDL 2.0.18.
1645
+ *
1646
+ * \sa SDL_RenderGeometry
1647
+ * \sa SDL_Vertex
1648
+ */
1649
+ extern DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer,
1650
+ SDL_Texture *texture,
1651
+ const float *xy, int xy_stride,
1652
+ const SDL_Color *color, int color_stride,
1653
+ const float *uv, int uv_stride,
1654
+ int num_vertices,
1655
+ const void *indices, int num_indices, int size_indices);
1656
+
1657
+ /**
1658
+ * Read pixels from the current rendering target to an array of pixels.
1659
+ *
1660
+ * **WARNING**: This is a very slow operation, and should not be used
1661
+ * frequently.
1662
+ *
1663
+ * `pitch` specifies the number of bytes between rows in the destination
1664
+ * `pixels` data. This allows you to write to a subrectangle or have padded
1665
+ * rows in the destination. Generally, `pitch` should equal the number of
1666
+ * pixels per row in the `pixels` data times the number of bytes per pixel,
1667
+ * but it might contain additional padding (for example, 24bit RGB Windows
1668
+ * Bitmap data pads all rows to multiples of 4 bytes).
1669
+ *
1670
+ * \param renderer the rendering context
1671
+ * \param rect an SDL_Rect structure representing the area to read, or NULL
1672
+ * for the entire render target
1673
+ * \param format an SDL_PixelFormatEnum value of the desired format of the
1674
+ * pixel data, or 0 to use the format of the rendering target
1675
+ * \param pixels a pointer to the pixel data to copy into
1676
+ * \param pitch the pitch of the `pixels` parameter
1677
+ * \returns 0 on success or a negative error code on failure; call
1678
+ * SDL_GetError() for more information.
1679
+ *
1680
+ * \since This function is available since SDL 2.0.0.
1054
1681
  */
1055
1682
  extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
1056
1683
  const SDL_Rect * rect,
@@ -1058,95 +1685,200 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
1058
1685
  void *pixels, int pitch);
1059
1686
 
1060
1687
  /**
1061
- * \brief Update the screen with rendering performed.
1688
+ * Update the screen with any rendering performed since the previous call.
1689
+ *
1690
+ * SDL's rendering functions operate on a backbuffer; that is, calling a
1691
+ * rendering function such as SDL_RenderDrawLine() does not directly put a
1692
+ * line on the screen, but rather updates the backbuffer. As such, you compose
1693
+ * your entire scene and *present* the composed backbuffer to the screen as a
1694
+ * complete picture.
1695
+ *
1696
+ * Therefore, when using SDL's rendering API, one does all drawing intended
1697
+ * for the frame, and then calls this function once per frame to present the
1698
+ * final drawing to the user.
1699
+ *
1700
+ * The backbuffer should be considered invalidated after each present; do not
1701
+ * assume that previous contents will exist between frames. You are strongly
1702
+ * encouraged to call SDL_RenderClear() to initialize the backbuffer before
1703
+ * starting each new frame's drawing, even if you plan to overwrite every
1704
+ * pixel.
1705
+ *
1706
+ * \param renderer the rendering context
1707
+ *
1708
+ * \since This function is available since SDL 2.0.0.
1709
+ *
1710
+ * \sa SDL_RenderClear
1711
+ * \sa SDL_RenderDrawLine
1712
+ * \sa SDL_RenderDrawLines
1713
+ * \sa SDL_RenderDrawPoint
1714
+ * \sa SDL_RenderDrawPoints
1715
+ * \sa SDL_RenderDrawRect
1716
+ * \sa SDL_RenderDrawRects
1717
+ * \sa SDL_RenderFillRect
1718
+ * \sa SDL_RenderFillRects
1719
+ * \sa SDL_SetRenderDrawBlendMode
1720
+ * \sa SDL_SetRenderDrawColor
1062
1721
  */
1063
1722
  extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer);
1064
1723
 
1065
1724
  /**
1066
- * \brief Destroy the specified texture.
1725
+ * Destroy the specified texture.
1067
1726
  *
1068
- * \sa SDL_CreateTexture()
1069
- * \sa SDL_CreateTextureFromSurface()
1727
+ * Passing NULL or an otherwise invalid texture will set the SDL error message
1728
+ * to "Invalid texture".
1729
+ *
1730
+ * \param texture the texture to destroy
1731
+ *
1732
+ * \since This function is available since SDL 2.0.0.
1733
+ *
1734
+ * \sa SDL_CreateTexture
1735
+ * \sa SDL_CreateTextureFromSurface
1070
1736
  */
1071
1737
  extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture);
1072
1738
 
1073
1739
  /**
1074
- * \brief Destroy the rendering context for a window and free associated
1075
- * textures.
1740
+ * Destroy the rendering context for a window and free associated textures.
1741
+ *
1742
+ * \param renderer the rendering context
1076
1743
  *
1077
- * \sa SDL_CreateRenderer()
1744
+ * \since This function is available since SDL 2.0.0.
1745
+ *
1746
+ * \sa SDL_CreateRenderer
1078
1747
  */
1079
1748
  extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
1080
1749
 
1081
1750
  /**
1082
- * \brief Force the rendering context to flush any pending commands to the
1083
- * underlying rendering API.
1751
+ * Force the rendering context to flush any pending commands to the underlying
1752
+ * rendering API.
1753
+ *
1754
+ * You do not need to (and in fact, shouldn't) call this function unless you
1755
+ * are planning to call into OpenGL/Direct3D/Metal/whatever directly in
1756
+ * addition to using an SDL_Renderer.
1757
+ *
1758
+ * This is for a very-specific case: if you are using SDL's render API, you
1759
+ * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set
1760
+ * SDL_HINT_RENDER_BATCHING to "1", and you plan to make OpenGL/D3D/whatever
1761
+ * calls in addition to SDL render API calls. If all of this applies, you
1762
+ * should call SDL_RenderFlush() between calls to SDL's render API and the
1763
+ * low-level API you're using in cooperation.
1084
1764
  *
1085
- * You do not need to (and in fact, shouldn't) call this function unless
1086
- * you are planning to call into OpenGL/Direct3D/Metal/whatever directly
1087
- * in addition to using an SDL_Renderer.
1765
+ * In all other cases, you can ignore this function. This is only here to get
1766
+ * maximum performance out of a specific situation. In all other cases, SDL
1767
+ * will do the right thing, perhaps at a performance loss.
1088
1768
  *
1089
- * This is for a very-specific case: if you are using SDL's render API,
1090
- * you asked for a specific renderer backend (OpenGL, Direct3D, etc),
1091
- * you set SDL_HINT_RENDER_BATCHING to "1", and you plan to make
1092
- * OpenGL/D3D/whatever calls in addition to SDL render API calls. If all of
1093
- * this applies, you should call SDL_RenderFlush() between calls to SDL's
1094
- * render API and the low-level API you're using in cooperation.
1769
+ * This function is first available in SDL 2.0.10, and is not needed in 2.0.9
1770
+ * and earlier, as earlier versions did not queue rendering commands at all,
1771
+ * instead flushing them to the OS immediately.
1095
1772
  *
1096
- * In all other cases, you can ignore this function. This is only here to
1097
- * get maximum performance out of a specific situation. In all other cases,
1098
- * SDL will do the right thing, perhaps at a performance loss.
1773
+ * \param renderer the rendering context
1774
+ * \returns 0 on success or a negative error code on failure; call
1775
+ * SDL_GetError() for more information.
1099
1776
  *
1100
- * This function is first available in SDL 2.0.10, and is not needed in
1101
- * 2.0.9 and earlier, as earlier versions did not queue rendering commands
1102
- * at all, instead flushing them to the OS immediately.
1777
+ * \since This function is available since SDL 2.0.10.
1103
1778
  */
1104
1779
  extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer);
1105
1780
 
1106
1781
 
1107
1782
  /**
1108
- * \brief Bind the texture to the current OpenGL/ES/ES2 context for use with
1109
- * OpenGL instructions.
1783
+ * Bind an OpenGL/ES/ES2 texture to the current context.
1784
+ *
1785
+ * This is for use with OpenGL instructions when rendering OpenGL primitives
1786
+ * directly.
1787
+ *
1788
+ * If not NULL, `texw` and `texh` will be filled with the width and height
1789
+ * values suitable for the provided texture. In most cases, both will be 1.0,
1790
+ * however, on systems that support the GL_ARB_texture_rectangle extension,
1791
+ * these values will actually be the pixel width and height used to create the
1792
+ * texture, so this factor needs to be taken into account when providing
1793
+ * texture coordinates to OpenGL.
1110
1794
  *
1111
- * \param texture The SDL texture to bind
1112
- * \param texw A pointer to a float that will be filled with the texture width
1113
- * \param texh A pointer to a float that will be filled with the texture height
1795
+ * You need a renderer to create an SDL_Texture, therefore you can only use
1796
+ * this function with an implicit OpenGL context from SDL_CreateRenderer(),
1797
+ * not with your own OpenGL context. If you need control over your OpenGL
1798
+ * context, you need to write your own texture-loading methods.
1114
1799
  *
1115
- * \return 0 on success, or -1 if the operation is not supported
1800
+ * Also note that SDL may upload RGB textures as BGR (or vice-versa), and
1801
+ * re-order the color channels in the shaders phase, so the uploaded texture
1802
+ * may have swapped color channels.
1803
+ *
1804
+ * \param texture the texture to bind to the current OpenGL/ES/ES2 context
1805
+ * \param texw a pointer to a float value which will be filled with the
1806
+ * texture width or NULL if you don't need that value
1807
+ * \param texh a pointer to a float value which will be filled with the
1808
+ * texture height or NULL if you don't need that value
1809
+ * \returns 0 on success, or -1 if the operation is not supported; call
1810
+ * SDL_GetError() for more information.
1811
+ *
1812
+ * \since This function is available since SDL 2.0.0.
1813
+ *
1814
+ * \sa SDL_GL_MakeCurrent
1815
+ * \sa SDL_GL_UnbindTexture
1116
1816
  */
1117
1817
  extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh);
1118
1818
 
1119
1819
  /**
1120
- * \brief Unbind a texture from the current OpenGL/ES/ES2 context.
1820
+ * Unbind an OpenGL/ES/ES2 texture from the current context.
1821
+ *
1822
+ * See SDL_GL_BindTexture() for examples on how to use these functions
1121
1823
  *
1122
- * \param texture The SDL texture to unbind
1824
+ * \param texture the texture to unbind from the current OpenGL/ES/ES2 context
1825
+ * \returns 0 on success, or -1 if the operation is not supported
1123
1826
  *
1124
- * \return 0 on success, or -1 if the operation is not supported
1827
+ * \since This function is available since SDL 2.0.0.
1828
+ *
1829
+ * \sa SDL_GL_BindTexture
1830
+ * \sa SDL_GL_MakeCurrent
1125
1831
  */
1126
1832
  extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
1127
1833
 
1128
1834
  /**
1129
- * \brief Get the CAMetalLayer associated with the given Metal renderer
1835
+ * Get the CAMetalLayer associated with the given Metal renderer.
1836
+ *
1837
+ * This function returns `void *`, so SDL doesn't have to include Metal's
1838
+ * headers, but it can be safely cast to a `CAMetalLayer *`.
1130
1839
  *
1131
- * \param renderer The renderer to query
1840
+ * \param renderer The renderer to query
1841
+ * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a
1842
+ * Metal renderer
1132
1843
  *
1133
- * \return CAMetalLayer* on success, or NULL if the renderer isn't a Metal renderer
1844
+ * \since This function is available since SDL 2.0.8.
1134
1845
  *
1135
- * \sa SDL_RenderGetMetalCommandEncoder()
1846
+ * \sa SDL_RenderGetMetalCommandEncoder
1136
1847
  */
1137
1848
  extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
1138
1849
 
1139
1850
  /**
1140
- * \brief Get the Metal command encoder for the current frame
1851
+ * Get the Metal command encoder for the current frame
1852
+ *
1853
+ * This function returns `void *`, so SDL doesn't have to include Metal's
1854
+ * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
1141
1855
  *
1142
- * \param renderer The renderer to query
1856
+ * Note that as of SDL 2.0.18, this will return NULL if Metal refuses to give
1857
+ * SDL a drawable to render to, which might happen if the window is
1858
+ * hidden/minimized/offscreen. This doesn't apply to command encoders for
1859
+ * render targets, just the window's backbacker. Check your return values!
1143
1860
  *
1144
- * \return id<MTLRenderCommandEncoder> on success, or NULL if the renderer isn't a Metal renderer
1861
+ * \param renderer The renderer to query
1862
+ * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the
1863
+ * renderer isn't a Metal renderer or there was an error.
1145
1864
  *
1146
- * \sa SDL_RenderGetMetalLayer()
1865
+ * \since This function is available since SDL 2.0.8.
1866
+ *
1867
+ * \sa SDL_RenderGetMetalLayer
1147
1868
  */
1148
1869
  extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * renderer);
1149
1870
 
1871
+ /**
1872
+ * Toggle VSync of the given renderer.
1873
+ *
1874
+ * \param renderer The renderer to toggle
1875
+ * \param vsync 1 for on, 0 for off. All other values are reserved
1876
+ * \returns a 0 int on success, or non-zero on failure
1877
+ *
1878
+ * \since This function is available since SDL 2.0.18.
1879
+ */
1880
+ extern DECLSPEC int SDLCALL SDL_RenderSetVSync(SDL_Renderer* renderer, int vsync);
1881
+
1150
1882
  /* Ends C function definitions when using C++ */
1151
1883
  #ifdef __cplusplus
1152
1884
  }