Rewrite the README and check missing features as of 2.0.7

3 files changed, 198 insertions, 288 deletions

diff --git a/README.asciidoc b/README.asciidoc
new file mode 100644
index 0000000..f4707bc
--- /dev/null
+++ b/README.asciidoc
@@ -0,0 +1,197 @@
+= ESDL2
+
+SDL2 Erlang NIF.
+
+The following sections list the state of the implementation
+as of SDL 2.0.7. The implementation is cut into sections
+corresponding to the public headers.
+
+== Fully implemented
+
+* 'SDL.h'
+* 'SDL_mouse.h'
+* 'SDL_filesystem.h'
+* 'SDL_power.h'
+
+== Partially implemented
+
+* 'SDL_blendmode.h': `SDL_BlendMode` is currently located in `sdl_renderer`. Move it. Everything else is missing.
+* 'SDL_clipboard.h': We currently do not support UTF-8. We should probably switch to binaries as input/output to support it.
+* 'SDL_cpuinfo.h': `SDL_HasAVX2` and `SDL_HasNEON` must be implemented.
+* 'SDL_events.h': Most of it is missing.
+* 'SDL_hints.h': We only have a proof of concept callback system.
+* 'SDL_keyboard.h': Most of it is missing.
+* 'SDL_render.h': The following elements are missing:
+** `SDL_TextureAccess` enum
+** `SDL_TextureModulate` enum
+** `SDL_GetNumRenderDrivers`
+** `SDL_GetRenderDriverInfo`
+** `SDL_CreateWindowAndRenderer` is currently located in `sdl_window`. Move it?
+** `SDL_CreateSoftwareRenderer`
+** `SDL_GetRenderer`
+** `SDL_GetRendererInfo`
+** `SDL_CreateTexture`
+** `SDL_QueryTexture`
+** `SDL_UpdateTexture`
+** `SDL_UpdateYUVTexture`
+** `SDL_LockTexture`
+** `SDL_UnlockTexture`
+** `SDL_SetRenderTarget`
+** `SDL_GetRenderTarget`
+** `SDL_RenderSetIntegerScale`
+** `SDL_RenderGetIntegerScale`
+** `SDL_RenderIsClipEnabled`
+** `SDL_RenderReadPixels`
+** `SDL_GL_BindTexture`
+** `SDL_GL_UnbindTexture`
+* 'SDL_stdinc.h': SDL_bool is implemented in 'sdl_bool.c'. Do we need anything else?
+* 'SDL_surface.h': Only surface creation (via `IMG_Load`) and destruction is implemented. Might be better to move IMG_* functions in their own space.
+* 'SDL_version.h': `SDL_GetRevisionNumber` must be implemented. The macros may also be useful.
+* 'SDL_video.h': The following elements are missing:
+** `SDL_WindowFlags` values SDL_WINDOW_ALWAYS_ON_TOP, SDL_WINDOW_SKIP_TASKBAR, SDL_WINDOW_UTILITY, SDL_WINDOW_TOOLTIP, SDL_WINDOW_POPUP_MENU, SDL_WINDOW_VULKAN
+** `SDL_WINDOWPOS_*` values for different displays
+** Window events are in sdl_events instead of sdl_window; `SDL_WINDOWEVENT_TAKE_FOCUS` and `SDL_WINDOWEVENT_HIT_TEST` are also missing.
+** `SDL_GetNumVideoDrivers`
+** `SDL_GetVideoDriver`
+** `SDL_VideoInit`
+** `SDL_VideoQuit`
+** `SDL_GetCurrentVideoDriver`
+** `SDL_GetNumVideoDisplays`
+** `SDL_GetDisplayName`
+** `SDL_GetDisplayBounds`
+** `SDL_GetDisplayDPI`
+** `SDL_GetDisplayUsableBounds`
+** `SDL_GetNumDisplayModes`
+** `SDL_GetDisplayMode`
+** `SDL_GetDesktopDisplayMode`
+** `SDL_GetCurrentDisplayMode`
+** `SDL_GetClosestDisplayMode`
+** `SDL_GetWindowDisplayIndex`
+** `SDL_SetWindowDisplayMode`
+** `SDL_GetWindowDisplayMode`
+** `SDL_GetWindowPixelFormat`
+** `SDL_CreateWindowFrom`
+** `SDL_GetWindowFromID`
+** We currently do not support UTF-8. We should probably switch to binaries as input/output to support it for `SDL_SetWindowTitle` and `SDL_GetWindowTitle`
+** `SDL_SetWindowData`
+** `SDL_GetWindowData`
+** `SDL_GetWindowBordersSize`
+** `SDL_SetWindowResizable`
+** `SDL_GetWindowSurface`
+** `SDL_UpdateWindowSurface`
+** `SDL_UpdateWindowSurfaceRects`
+** `SDL_GetGrabbedWindow`
+** `SDL_SetWindowOpacity`
+** `SDL_GetWindowOpacity`
+** `SDL_SetWindowModalFor`
+** `SDL_SetWindowInputFocus`
+** `SDL_SetWindowGammaRamp`
+** `SDL_GetWindowGammaRamp`
+** `SDL_SetWindowHitTest` and the related callback `SDL_HitTestResult`
+** `SDL_IsScreenSaverEnabled`
+** `SDL_EnableScreenSaver`
+** `SDL_DisableScreenSaver`
+** `SDL_GL_LoadLibrary` (unclear if we need it)
+** `SDL_GL_GetProcAddress` (unclear if we need it)
+** `SDL_GL_UnloadLibrary` (unclear if we need it)
+** `SDL_GL_ExtensionSupported`
+** `SDL_GL_ResetAttributes`
+** `SDL_GL_SetAttribute`
+** `SDL_GL_GetAttribute`
+** `SDL_GL_MakeCurrent`
+** `SDL_GL_GetCurrentWindow`
+** `SDL_GL_GetCurrentContext`
+** `SDL_GL_GetDrawableSize`
+** `SDL_GL_SetSwapInterval`
+** `SDL_GL_GetSwapInterval`
+
+== To be implemented
+
+* 'SDL_audio.h'
+* 'SDL_error.h' (for completion)
+* 'SDL_gamecontroller.h'
+* 'SDL_gesture.h'
+* 'SDL_haptic.h'
+* 'SDL_joystick.h'
+* 'SDL_keycode.h'
+* 'SDL_messagebox.h'
+* 'SDL_pixels.h'
+* 'SDL_platform.h'
+* 'SDL_rect.h' (though we have a rect data type in sdl_renderer)
+* 'SDL_rwops.h' (unclear if we need it)
+* 'SDL_scancode.h'
+* 'SDL_shape.h'
+* 'SDL_system.h'
+* 'SDL_syswm.h'
+* 'SDL_timer.h' (unclear if we need it)
+* 'SDL_touch.h'
+* 'SDL_vulkan.h'
+
+For OpenGL we need to figure out whether we can call the functions from
+wxErlang. If we can, great! If not, find an automated way to provide
+access to OpenGL.
+
+SDL extensions also need to be investigated and implemented.
+
+== To be removed
+
+* `SDL_SetMainReady` which has no public interface, only the NIF function.
+
+== Don't implement
+
+These don't make a lot of sense for Erlang.
+
+* 'SDL_assert.h'
+* 'SDL_atomic.h'
+* 'SDL_bits.h'
+* 'SDL_endian.h'
+* 'SDL_loadso.h'
+* 'SDL_log.h'
+* 'SDL_main.h'
+* 'SDL_mutex.h'
+* 'SDL_quit.h' (only necessary when using `SDL_Main`?)
+* 'SDL_thread.h'
+
+== Nothing to implement
+
+These are either private headers, duplicated OpenGL/Vulkan
+headers or simply deprecated.
+
+* 'SDL_config.h'
+* 'SDL_config_android.h'
+* 'SDL_config_iphoneos.h'
+* 'SDL_config_macosx.h'
+* 'SDL_config_minimal.h'
+* 'SDL_config_pandora.h'
+* 'SDL_config_psp.h'
+* 'SDL_config_windows.h'
+* 'SDL_config_winrt.h'
+* 'SDL_config_wiz.h'
+* 'SDL_copying.h'
+* 'SDL_egl.h'
+* 'SDL_name.h'
+* 'SDL_opengl.h'
+* 'SDL_opengl_glext.h'
+* 'SDL_opengles.h'
+* 'SDL_opengles2.h'
+* 'SDL_opengles2_gl2.h'
+* 'SDL_opengles2_gl2ext.h'
+* 'SDL_opengles2_gl2platform.h'
+* 'SDL_opengles2_khrplatform.h'
+* 'SDL_revision.h'
+* 'SDL_test.h'
+* 'SDL_test_assert.h'
+* 'SDL_test_common.h'
+* 'SDL_test_compare.h'
+* 'SDL_test_crc32.h'
+* 'SDL_test_font.h'
+* 'SDL_test_fuzzer.h'
+* 'SDL_test_harness.h'
+* 'SDL_test_images.h'
+* 'SDL_test_log.h'
+* 'SDL_test_md5.h'
+* 'SDL_test_memory.h'
+* 'SDL_test_random.h'
+* 'SDL_types.h'
+* 'begin_code.h'
+* 'close_code.h'
diff --git a/README.md b/README.md
deleted file mode 100644
index 35e931a..0000000
--- a/README.md
+++ /dev/null
@@ -1,287 +0,0 @@
-ESDL2
-=====
-
-SDL2 Erlang NIF.
-
-Status
-------
-
-Week-end project. Work in progress.
-
-The following limitations apply:
-
- *  Erlang 17.0+ is required
- *  SDL 2.0.3+ is required
- *  No support for UTF-8 strings, only Latin-1
-
-The following ideas need to be investigated:
-
- *  We may benefit from the reference receive optimization when doing calls
- *  We may want a way to pipeline draw operations
- *  Using HiPE mutable bytearrays for "void* pixels" types
-
-The following tasks remain to be done:
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_hints.h
-  * We need to implement everything.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_error.h
-  * Anything that can produce errors will have an automatic call to SDL_GetError.
-  * I am not sure we need any direct access to those functions.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_log.h
-  * We already have logging in Erlang. Not sure we need this.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_assert.h
-  * I am not sure we need this, and we can't use the assert macro directly anyway.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_version.h
-  * It might be useful to provide access to some of the macros as functions.
-  * The SDL_GetRevisionNumber function needs to be implemented.
-  * It might be interesting to use the macros to conditionally implement some features,
-    this way we could be compatible with all versions >= 2.0.0.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_video.h
-  * The SDL_DisplayMode structure and related functions need to be implemented:
-    * SDL_GetNumDisplayModes()
-    * SDL_GetDisplayMode()
-    * SDL_GetDesktopDisplayMode()
-    * SDL_GetCurrentDisplayMode()
-    * SDL_GetClosestDisplayMode()
-    * SDL_SetWindowDisplayMode()
-    * SDL_GetWindowDisplayMode()
-  * Most other display functions are also not implemented:
-    * SDL_GetNumVideoDisplays()
-	* SDL_GetDisplayName()
-	* SDL_GetDisplayBounds()
-	* SDL_GetDisplayDPI()
-  * Some window functions need to be implemented:
-    * SDL_CreateWindowFrom()
-	* SDL_GetWindowData()
-	* SDL_SetWindowData()
-    * SDL_GetWindowPixelFormat()
-	* SDL_GetWindowFromID()
-	* SDL_GetWindowSurface()
-	* SDL_UpdateWindowSurface()
-	* SDL_UpdateWindowSurfaceRects()
-	* SDL_GetGrabbedWindow()
-	* SDL_SetWindowGammaRamp()
-	* SDL_GetWindowGammaRamp()
-	* SDL_SetWindowModalFor()
-	* SDL_SetWindowInputFocus()
-	* SDL_SetWindowOpacity()
-	* SDL_GetWindowOpacity()
-	* SDL_SetWindowResizable()
-  * There is an SDL_WINDOW_MOUSE_CAPTURE window flag we need to implement.
-  * There are two window pos flags, related to multi monitors, that we don't support:
-    * SDL_WINDOWPOS_UNDEFINED_DISPLAY(X)
-	* SDL_WINDOWPOS_CENTERED_DISPLAY(X)
-  * We do not support OpenGL at all yet:
-    * SDL_GLContext
-	* SDL_GLattr
-	* SDL_GLprofile
-	* SDL_GLcontextFlag
-	* SDL_GLcontextReleaseFlag
-	* SDL_GL_LoadLibrary()
-	* SDL_GL_GetProcAddress()
-	* SDL_GL_UnloadLibrary()
-	* SDL_GL_ExtensionSupported()
-	* SDL_GL_ResetAttributes()
-	* SDL_GL_SetAttribute()
-	* SDL_GL_GetAttribute()
-	* SDL_GL_MakeCurrent()
-	* SDL_GL_GetCurrentWindow()
-	* SDL_GL_GetCurrentContext()
-	* SDL_GL_GetDrawableSize()
-	* SDL_GL_SetSwapInterval()
-	* SDL_GL_GetSwapInterval()
-  * We do not support any of the video driver related functions:
-    * SDL_GetNumVideoDrivers()
-	* SDL_GetVideoDriver()
-	* SDL_VideoInit()
-	* SDL_VideoQuit()
-	* SDL_GetCurrentVideoDriver()
-  * Flags and functions relating to SDL_HitTest are not implemented:
-    * SDL_HitTestResult
-	* SDL_HitTest() callback
-	* SDL_SetWindowHitTest()
-  * Screensaver related functions are not implemented:
-    * SDL_IsScreenSaverEnabled()
-	* SDL_EnableScreenSaver()
-	* SDL_DisableScreenSaver()
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_render.h
-  * The SDL_RendererInfo structure and related functions are not implemented:
-    * SDL_GetRenderDriverInfo()
-	* SDL_GetRendererInfo()
-  * The SDL_TextureAccess enum is not implemented.
-  * The SDL_TextureModulate enum is not implemented.
-  * A number of other functions are not implemented:
-    * SDL_CreateSoftwareRenderer()
-	* SDL_GetRenderer()
-	* SDL_CreateTexture()
-	* SDL_QueryTexture()
-	* SDL_UpdateTexture()
-	* SDL_UpdateYUVTexture()
-	* SDL_LockTexture()
-	* SDL_UnlockTexture()
-	* SDL_SetRenderTarget()
-	* SDL_GetRenderTarget()
-	* SDL_RenderIsClipEnabled()
-	* SDL_RenderReadPixels()
-	* SDL_RenderSetIntegerScale()
-  * We do not support OpenGL at all yet:
-    * SDL_GL_BindTexture()
-	* SDL_GL_UnbindTexture()
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_pixels.h
-  * We need to implement everything.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_rect.h
-  * We need to implement everything, though we already have points and rects as maps elsewhere.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_surface.h
-  * We need to implement everything except SDL_FreeSurface().
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_syswm.h
-  * We need to implement everything.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_events.h
-  * The following event types need to be implemented:
-    * SDL_APP_TERMINATING (iOS and Android)
-	* SDL_APP_LOWMEMORY (iOS and Android)
-	* SDL_APP_WILLENTERBACKGROUND (iOS and Android)
-	* SDL_APP_DIDENTERBACKGROUND (iOS and Android)
-	* SDL_APP_WILLENTERFOREGROUND (iOS and Android)
-	* SDL_APP_DIDENTERFOREGROUND (iOS and Android)
-	* SDL_SYSWMEVENT (SDL_SysWMEvent, SDL_SysWMmsg)
-	* SDL_TEXTEDITING (SDL_TEXTEDITINGEVENT_TEXT_SIZE, SDL_TextEditingEvent)
-	* SDL_TEXTINPUT (SDL_TEXTINPUTEVENT_TEXT_SIZE, SDL_TextInputEvent)
-	* SDL_JOYAXISMOTION (SDL_JoyAxisEvent)
-	* SDL_JOYBALLMOTION (SDL_JoyBallEvent)
-	* SDL_JOYHATMOTION (SDL_JoyHatEvent)
-	* SDL_JOYBUTTONDOWN (SDL_JoyButtonEvent)
-	* SDL_JOYBUTTONUP (SDL_JoyButtonEvent)
-	* SDL_JOYDEVICEADDED (SDL_JoyDeviceEvent)
-	* SDL_JOYDEVICEREMOVED (SDL_JoyDeviceEvent)
-	* SDL_CONTROLLERAXISMOTION (SDL_ControllerAxisEvent)
-	* SDL_CONTROLLERBUTTONDOWN (SDL_ControllerButtonEvent)
-	* SDL_CONTROLLERBUTTONUP (SDL_ControllerButtonEvent)
-	* SDL_CONTROLLERDEVICEADDED (SDL_ControllerDeviceEvent)
-	* SDL_CONTROLLERDEVICEREMOVED (SDL_ControllerDeviceEvent)
-	* SDL_CONTROLLERDEVICEREMAPPED (SDL_ControllerDeviceEvent)
-	* SDL_FINGERDOWN (SDL_TouchFingerEvent)
-	* SDL_FINGERUP (SDL_TouchFingerEvent)
-	* SDL_FINGERMOTION (SDL_TouchFingerEvent)
-	* SDL_DOLLARGESTURE (SDL_DollarGestureEvent)
-	* SDL_DOLLARRECORD (SDL_DollarGestureEvent)
-	* SDL_MULTIGESTURE (SDL_MultiGestureEvent)
-	* SDL_CLIPBOARDUPDATE
-	* SDL_DROPFILE (SDL_DropEvent)
-	* SDL_AUDIODEVICEADDED (SDL_AudioDeviceEvent)
-	* SDL_AUDIODEVICEREMOVED (SDL_AudioDeviceEvent)
-	* SDL_RENDER_TARGETS_RESET
-	* SDL_RENDER_DEVICE_RESET
-	* SDL_WINDOWEVENT_HIT_TEST
-	* SDL_WINDOWEVENT_TAKE_FOCUS
-	* SDL_KEYMAPCHANGED
-	* User defined events, from SDL_USEREVENT to SDL_LASTEVENT (SDL_UserEvent)
-  * We currently do not handle the SDL_MouseMotionEvent.state value
-  * We currently do not handle the SDL_MouseWheelEvent.direction value (SDL >= 2.0.4, unreleased yet)
-  * We need to implement the following functions:
-    * SDL_PumpEvents()
-	* SDL_PeepEvents()
-	* SDL_HasEvent()
-	* SDL_HasEvents()
-	* SDL_FlushEvent()
-	* SDL_FlushEvents()
-	* SDL_WaitEvent()
-	* SDL_WaitEventTimeout()
-	* SDL_PushEvent()
-	* SDL_SetEventFilter()
-	* SDL_GetEventFilter()
-	* SDL_AddEventWatch()
-	* SDL_DelEventWatch()
-	* SDL_FilterEvents()
-	* SDL_EventState()
-	* SDL_RegisterEvents()
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_keyboard.h
-  * We need to implement the following functions:
-  	* SDL_GetKeyboardFocus()
-	* SDL_GetKeyboardState()
-	* SDL_GetModState()
-	* SDL_SetModState()
-	* SDL_GetKeyFromScancode()
-	* SDL_GetScancodeFromKey()
-	* SDL_GetScancodeName()
-	* SDL_GetScancodeFromName()
-	* SDL_GetKeyName()
-	* SDL_GetKeyFromName()
-	* SDL_SetTextInputRect()
-	* SDL_HasScreenKeyboardSupport()
-	* SDL_IsScreenKeyboardShown()
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_keycode.h
-  * We probably should make it easy to identify keycodes and scancodes.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_scancode.h
-  * We probably should make it easy to identify keycodes and scancodes.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_joystick.h
-  * We need to implement everything.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_gamecontroller.h
-  * We need to implement everything.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_haptic.h
-  * We need to implement everything.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_audio.h
-  * We need to implement everything.
-  * We might want to implement SDL_mixer first.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_thread.h
-  * We don't really need this for Erlang, do we?
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_mutex.h
-  * We don't really need this for Erlang, do we?
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_atomic.h
-  * We don't really need this for Erlang, do we?
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_timer.h
-  * We need to implement everything.
-  * It's not the most useful to have, but doesn't hurt to have it.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_rwops.h
-  * We need to implement everything.
-  * It's currently unclear if and how this should be implemented.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_loadso.h
-  * We don't really need this for Erlang, do we?
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_platform.h
-  * We need to implement the one function in there. Can always be useful.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_cpuinfo.h
-  * The function SDL_HasAVX2() needs to be implemented. (SDL >= 2.0.4, unreleased yet)
-  * SDL_HasNEON()
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_endian.h
-  * We need to implement everything.
-  * It's currently unclear if and how this should be implemented.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_bits.h
-  * We need to implement everything.
-  * It's currently unclear if and how this should be implemented.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_system.h
-  * We need to implement everything.
-  * It's currently unclear if and how this should be implemented.
-
-* http://hg.libsdl.org/SDL/file/default/include/SDL_stdinc.h
-  * Nothing except support for SDL_bool was implemented.
-  * There might be useful bits and pieces in there, in particular the math or iconv functions.
-
-* SDL_image, SDL_mixer, ... also need to be investigated and implemented.
diff --git a/c_src/sdl_window.c b/c_src/sdl_window.c
index c286da0..4ac3604 100644
--- a/c_src/sdl_window.c
+++ b/c_src/sdl_window.c
@@ -25,7 +25,6 @@ void dtor_Window(ErlNifEnv* env, void* obj)
 
 #define WINDOW_FLAGS(F) \
 	F(fullscreen, SDL_WINDOW_FULLSCREEN) \
-	F(fullscreen_desktop, SDL_WINDOW_FULLSCREEN_DESKTOP) \
 	F(opengl, SDL_WINDOW_OPENGL) \
 	F(shown, SDL_WINDOW_SHOWN) \
 	F(hidden, SDL_WINDOW_HIDDEN) \
@@ -36,6 +35,7 @@ void dtor_Window(ErlNifEnv* env, void* obj)
 	F(input_grabbed, SDL_WINDOW_INPUT_GRABBED) \
 	F(input_focus, SDL_WINDOW_INPUT_FOCUS) \
 	F(mouse_focus, SDL_WINDOW_MOUSE_FOCUS) \
+	F(fullscreen_desktop, SDL_WINDOW_FULLSCREEN_DESKTOP) \
 	F(foreign, SDL_WINDOW_FOREIGN) \
 	F(allow_high_dpi, SDL_WINDOW_ALLOW_HIGHDPI) \
 	F(mouse_capture, SDL_WINDOW_MOUSE_CAPTURE)