|
|
= ESDL2
SDL2 Erlang NIF.
This project tries to implement SDL2 and some of its
extensions in one convenient NIF. The supported versions
and features are listed below.
* SDL 2.0.7
* SDL_ttf 2.0.14
The implementation is cut into sections corresponding
to the public headers.
== Fully implemented
* 'SDL.h'
* 'SDL_blendmode.h'
* 'SDL_clipboard.h'
* 'SDL_cpuinfo.h'
* 'SDL_filesystem.h'
* 'SDL_keyboard.h'
* 'SDL_keycode.h'
* 'SDL_mouse.h'
* 'SDL_platform.h'
* 'SDL_power.h'
* 'SDL_rect.h'
* 'SDL_scancode.h'
== Partially implemented
* 'SDL_events.h': The following events and functions are missing:
** `SDL_SYSWMEVENT`
** `SDL_TEXTEDITING`
** `SDL_TEXTINPUT`
** `SDL_JOYAXISMOTION`
** `SDL_JOYBALLMOTION`
** `SDL_JOYHATMOTION`
** `SDL_JOYBUTTONDOWN`
** `SDL_JOYBUTTONUP`
** `SDL_JOYDEVICEADDED`
** `SDL_JOYDEVICEREMOVED`
** `SDL_CONTROLLERAXISMOTION`
** `SDL_CONTROLLERBUTTONDOWN`
** `SDL_CONTROLLERBUTTONUP`
** `SDL_CONTROLLERDEVICEADDED`
** `SDL_CONTROLLERDEVICEREMOVED`
** `SDL_CONTROLLERDEVICEREMAPPED`
** `SDL_FINGERDOWN`
** `SDL_FINGERUP`
** `SDL_FINGERMOTION`
** `SDL_DOLLARGESTURE`
** `SDL_DOLLARRECORD`
** `SDL_MULTIGESTURE`
** `SDL_DROPFILE`
** `SDL_DROPTEXT`
** `SDL_DROPBEGIN`
** `SDL_DROPCOMPLETE`
** `SDL_AUDIODEVICEADDED`
** `SDL_AUDIODEVICEREMOVED`
** `SDL_PeepEvents` with action argument `SDL_ADDEVENT`
** `SDL_PushEvents`
** `SDL_SetEventFilter`
** `SDL_GetEventFilter`
** `SDL_AddEventWatch`
** `SDL_DelEventWatch`
** `SDL_FilterEvents`
** `SDL_EventState` and `SDL_GetEventState`
** `SDL_RegisterEvents`
* 'SDL_hints.h': We only have a proof of concept callback system.
* 'SDL_pixels.h': Only the pixel format enum and conversion function is defined.
* 'SDL_render.h': The following elements are missing:
** `SDL_TextureAccess` enum
** `SDL_TextureModulate` enum
** `SDL_CreateWindowAndRenderer` is currently located in `sdl_window`. Move it?
** `SDL_CreateSoftwareRenderer` (renderer)
** `SDL_CreateTexture` (texture)
** `SDL_QueryTexture` (texture)
** `SDL_UpdateTexture` (texture)
** `SDL_UpdateYUVTexture` (texture)
** `SDL_LockTexture` (texture)
** `SDL_UnlockTexture` (texture)
** `SDL_SetRenderTarget` (renderer)
** `SDL_GetRenderTarget` (renderer)
** `SDL_RenderIsClipEnabled` (renderer)
** `SDL_RenderReadPixels` (renderer)
* 'SDL_stdinc.h': Erlang does not come with the functions `copysign` and `scalbn`.
* 'SDL_surface.h': Only surface creation (via `IMG_Load`) and destruction is implemented. Might be better to move IMG_* functions in their own space.
** Everything in this header can be implemented as simple functions (as opposed to cast/call).
** We'll need to add functions to retrieve the pixel format and possibly pitch (though format+dimensions is enough to get it).
** We'll need to add extra functions for direct access to the pixels.
* 'SDL_ttf.h':
** A function to obtain the SDL_ttf version could be useful
** `TTF_Linked_Version` (if it makes sense, depends on how the library is loaded)
** `TTF_OpenFontRW` (unclear if we need it)
** `TTF_OpenFontIndexRW` (unclear if we need it)
* 'SDL_version.h': `SDL_GetRevisionNumber` must be implemented. The macros may also be useful.
* 'SDL_video.h': The following elements are missing:
** `SDL_WINDOWPOS_*` values for different displays
** `SDL_GetWindowSurface` (window)
** `SDL_UpdateWindowSurface` (window)
** `SDL_UpdateWindowSurfaceRects` (window)
== To be implemented
* 'SDL_audio.h'
* 'SDL_error.h' (for completion)
* 'SDL_gamecontroller.h'
* 'SDL_gesture.h'
* 'SDL_haptic.h'
* 'SDL_joystick.h'
* 'SDL_messagebox.h'
* 'SDL_rwops.h' (unclear if we need it)
* 'SDL_shape.h'
* 'SDL_system.h'
* 'SDL_syswm.h'
* 'SDL_timer.h' (unclear if we need it)
* 'SDL_touch.h'
Other SDL extensions need to be investigated and implemented.
We definitely want at least some of SDL_image and SDL_mixer.
We probably do not need SDL_net or SDL_rtf.
== OpenGL and Vulkan
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.
The following functions are related to OpenGL and Vulkan and still
need to be implemented:
* 'SDL_render.h':
** `SDL_GL_BindTexture`
** `SDL_GL_UnbindTexture`
* 'SDL_video.h':
** `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`
* 'SDL_vulkan.h'
== 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_events.h': the functions `SDL_WaitEvent` and `SDL_WaitEventTimeout` are blocking.
* 'SDL_loadso.h'
* 'SDL_log.h'
* 'SDL_main.h'
* 'SDL_mutex.h'
* 'SDL_quit.h' (only necessary when using `SDL_Main`?)
* 'SDL_stdinc.h': only a few functions are implemented, others are not interesting.
* 'SDL_thread.h'
* 'SDL_ttf.h': the rendering functions for `Text` and `UNICODE` are not interesting because they internally call the `UTF8` functions so we may as well provide utf8-encoded binaries directly. The `TTF_ByteSwappedUNICODE` also falls in this category and is not provided.
* 'SDL_video.h': the functions `SDL_CreateWindowFrom`, `SDL_SetWindowData` and `SDL_GetWindowData` take external data as argument.
== 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'
== Thoughts on callbacks
SDL2 has a number of callback interfaces. While we probably
do not want to implement some of them (like the OS-specific
callbacks for Windows and iOS) we do need others.
Callbacks that have no return value are easy to implement.
The idea is to have an Erlang process that waits for messages
containing the callback MFA to execute. The following callbacks
have no return value and no other caveat:
* `SDL_AudioCallback`
* `SDL_iOSSetAnimationCallback` (iOS)
* `SDL_SetWindowsMessageHook` (Windows)
The callback functions for hints do not have a return value
either, but they have an extra caveat: there can be more
than one per hint. SDL2 identifies these callbacks with the
tuple `(callback, userdata)` and we need to give SDL2 this
same tuple in order to remove the callback.
The best way to handle this is probably to do it mostly via
Erlang where a process would take care of the callbacks and
would enable/disable the SDL2 callbacks when required. The
`userdata` would in this case always be `NULL` since all the
handling would be done from the Erlang side.
The alternative would be to create a resource per callback
that the user would have to keep around and that's not very
convenient.
The functions in question are:
* `SDL_AddHintCallback`
* `SDL_DelHintCallback`
Other callbacks have a return value but otherwise work in a
slightly different manner from each other. The callback can
be invoked in a similar manner to others, by sending a message
to the Erlang code. The difficulty comes in returning the
result to the NIF code. The solution for doing that
will vary depending on the callback in question.
There can be one window hit test callback per window. This
means we can use the window's user data for storing the
result and then signal the NIF to read from it using the
NIF mutex/cond mechanism. Both of those can also be stored
in the window's user data.
This means the window must be sent to Erlang and passed
back to the NIF when giving the result back, which should
be trivial. The callback data can stay empty since we
store everything in the window data.
The function in question is:
* `SDL_SetWindowHitTest`
The final set of callbacks is timers. When you add a timer
it returns a `TimerID` and you can use it to remove the
timer. In addition, the callback can decide to change the
timer interval or to stop the timer. Unlike for windows
there is no way to attach information to a `TimerID` so
a separate solution will be necessary. Since there can
be any number of timers and they can fire off at any
time then some kind of queue will be necessary to store
return values.
Even though we don't know the `TimerID` when setting up
the timer, we should be able to keep it around in the
same data structure used for the callback extra parameter.
There is however the concern of memory allocation: we
will probably need to hook into all functions that can
remove timers to make sure we free the memory we allocated
too.
They're the hardest callback functions to implement, but
thankfully they're also some of the least interesting
considering Erlang already comes with many ways to deal
with timers.
Even if we do implement them, their scope may be reduced
so that we always return the same interval as a return
value and therefore don't allow changing the interval or
stopping the timer from inside a timer callback.
The functions in question are:
* `SDL_AddTimer`
* `SDL_RemoveTimer`
Other than hints, it should be possible to have a common
mechanism for all callbacks. The following messages may
be sent from the NIF:
* `{callback, M, F, Args}` for `void`
* `{callback, M, F, Args, ResF, ResExtraArg}` for others
The `esdl2:ResF(Result, ResExtraArg)` function would be
called in the second case after the callback returns.
The NIF function can then decide what the appropriate
behavior is for sending the result back to the SDL2
callback.
The main concern when dealing with SDL2 callbacks is
the memory allocations since SDL2 will not free the
memory we allocate. Solutions should be extra careful
not to introduce leaks and try to avoid allocating
memory entirely for callbacks. When not possible then
the memory must be allocated and freed in the course
of running the Erlang callback and not be kept any
longer.
|
