Current status of SDL.

2026-05-13 19:48:22 +00:00
parent 28e9c4ba18
commit 15bb051619
24 changed files with 1806 additions and 360 deletions
@@ -0,0 +1,190 @@
+# HDK-SDL wrapper
+
+HDK-SDL uses the grid `SharedPtrWrapper` to create relatively light-weight reference wrappers around pointers to SDL3 primitives.
+
+Use classes without declaring pointers to them, knowing that copying or referencing is relatively cheap and that the underlying SDL3 primitive will be properly managed and cleaned up when no longer needed.
+
+## Dependencies
+
+- holodeck-grid
+- [SDL3](https://www.libsdl.org/)
+
+## Naming Conventions
+
+API that is 1 to 1 with SDL with otherwise minimal wrapping will be as close to the original SDL function call as possible: for example, `SDL_CreateWindow` will be wrapped by `hd::sdl::Window::Create`.
+
+To update a surface, the original SDL function is `SDL_UpdateWindowSurface(SDL_Window* window)`, and the wrapper will be `window.UpdateSurface()`.
+
+So on and so forth.  But there are some exceptions and edge cases.
+
+For example when `Blit`ing a surface, the original SDL function is `SDL_BlitSurface`, but the wrapper will expose two alternatives: `BlitTo` and `BlitFrom`, each implying that `this*` is the source or destination of the blit, respectively.  In this case not only is the function name changed, but the parameters are also rearranged to be more intuitive and consistent with the implied source/destination of the blit.
+
+## Default values
+
+While done sparingly, some wrapper methods may provide default values for parameters that are commonly used with a specific value.  For example when the last parameter of a function is an optional pointer it may be defaulted to `nullptr` in the wrapper method, so that the caller can omit it when they don't need it.  Sensible defaults may also be provided elsewhere.
+
+## Headers
+
+Within `include/hdk/sdl` there are folders for each SDL3 header files, and within each files for corresponding wrappers of SDL3 primitive types.  Basically if SDL3 lets you "create" a primitive, use that primitive with some functions, and then "destroy" that primitive, there should be a wrapper for that primitive in the corresponding header file.  The prime example is `include/hd/sdl/video/Window.hpp` which contains the `hd::sdl::video::Window` wrapper for `SDL_Window`
+
+With this entirely header-only and inline design, there is no need for a corresponding .cpp and the resulting compiled code should be as efficient as if you were using the raw SDL3 API directly, while still benefiting from the safety and convenience of C++ RAII and wrapper classes.
+
+## SDL API Coverage
+
+Most links are from Links from [API by Category](https://wiki.libsdl.org/SDL3/APIByCategory), then those respective pages are used to fill in the rest of the checklist.
+
+In progress/complete:
+
+- By category:
+- [ ] BASICS
+  - [~] [Category Video][]
+    - [x] `hdk::sdl::Window`
+    - [x] `hdk::sdl::Display`
+  - [ ] [Category Surface][]
+    - [x] `hdk::sdl::Surface`
+  - [ ] [Category Main][]
+  - [ ] [Category Init][]
+  - [ ] [Category Hints][]
+  - [x] [Category Properties][]
+  - [ ] [Category Error][]
+  - [ ] [Category Log][]
+  - [ ] [Category Assert][]
+  - [ ] [Category Version][]
+  - [ ] [Category Events][]
+  - [ ] [Category Keyboard][]
+  - [ ] [Category Keycode][]
+  - [ ] [Category Scancode][]
+  - [ ] [Category Mouse][]
+  - [ ] [Category Joystick][]
+  - [ ] [Category Gamepad][]
+  - [ ] [Category Touch][]
+  - [ ] [Category Pen][]
+  - [ ] [Category Sensor][]
+  - [ ] [Category HIDAPI][]
+- [ ] [Category Render][]
+- [ ] [Category Pixels][]
+- [ ] [Category Blendmode][]
+- [ ] [Category Rect][]
+- [ ] [Category Clipboard][]
+- [ ] [Category Vulkan][]
+- [ ] [Category Metal][]
+- [ ] [Category Camera][]
+- [ ] HAPTIC
+  - [ ] [Category Haptic][]
+- [ ] AUDIO
+  - [ ] [Category Audio][]
+- [ ] GPU
+  - [ ] [Category GPU][]
+- [ ] Time
+  - [ ] [Category Timer][]
+  - [ ] [Category Time][]
+- [ ] THREADS
+  - [ ] [Category Thread][]
+  - [ ] [Category Mutex][]
+  - [ ] [Category Atomic][]
+- [ ] FILE I/O
+  - [ ] [Category Filesystem][]
+  - [ ] [Category Storage][]
+  - [ ] [Category IOStream][]
+  - [ ] [Category AsyncIO][]
+- [ ] PLATFORM
+  - [ ] [Category Platform][]
+  - [ ] [Category CPUInfo][]
+  - [ ] [Category Intrinsics][]
+  - [ ] [Category Endian][]
+  - [ ] [Category Bits][]
+- [ ] MISC
+  - [N] [Category Shared Object][]
+  - [ ] [Category Process][]
+  - [ ] [Category Power][]
+  - [ ] [Category Messagebox][]
+  - [ ] [Category Dialog][]
+  - [ ] [Category Tray][]
+  - [ ] [Category Locale][]
+  - [ ] [Category System][]
+  - [ ] [Category Stdinc][]
+  - [ ] [Category GUID][]
+  - [ ] [Category Misc][]
+
+<!--A-->
+[Category Shared Object]: <https://wiki.libsdl.org/SDL3/CategorySharedObject>
+[Category Assert]: https://wiki.libsdl.org/SDL3/CategoryAssert
+[Category AsyncIO]: <https://wiki.libsdl.org/SDL3/CategoryAsyncIO>
+[Category Atomic]: <https://wiki.libsdl.org/SDL3/CategoryAtomic>
+[Category Audio]: <https://wiki.libsdl.org/SDL3/CategoryAudio>
+<!--B-->
+[Category Bits]: <https://wiki.libsdl.org/SDL3/CategoryBits>
+[Category Blendmode]: <https://wiki.libsdl.org/SDL3/CategoryBlendmode>
+<!--C-->
+[Category Camera]: <https://wiki.libsdl.org/SDL3/CategoryCamera>
+[Category CPUInfo]: <https://wiki.libsdl.org/SDL3/CategoryCPUInfo>
+<!--D-->
+[Category Dialog]: <https://wiki.libsdl.org/SDL3/CategoryDialog>
+<!--E-->
+[Category Endian]: <https://wiki.libsdl.org/SDL3/CategoryEndian>
+[Category Error]: https://wiki.libsdl.org/SDL3/CategoryError
+[Category Events]: <https://wiki.libsdl.org/SDL3/CategoryEvents>
+<!--F-->
+[Category Filesystem]: <https://wiki.libsdl.org/SDL3/CategoryFilesystem>
+<!--G-->
+[Category Gamepad]: <https://wiki.libsdl.org/SDL3/CategoryGamepad>
+[Category GPU]: <https://wiki.libsdl.org/SDL3/CategoryGPU>
+[Category GUID]: <https://wiki.libsdl.org/SDL3/CategoryGUID>
+<!--H-->
+[Category Haptic]: <https://wiki.libsdl.org/SDL3/CategoryHaptic>
+[Category HIDAPI]: <https://wiki.libsdl.org/SDL3/CategoryHIDAPI>
+[Category Hints]: https://wiki.libsdl.org/SDL3/CategoryHints
+<!--I-->
+[Category Init]: https://wiki.libsdl.org/SDL3/CategoryInit
+[Category Intrinsics]: <https://wiki.libsdl.org/SDL3/CategoryIntrinsics>
+[Category IOStream]: <https://wiki.libsdl.org/SDL3/CategoryIOStream>
+<!--J-->
+[Category Joystick]: <https://wiki.libsdl.org/SDL3/CategoryJoystick>
+<!--K-->
+[Category Keyboard]: <https://wiki.libsdl.org/SDL3/CategoryKeyboard>
+[Category Keycode]: <https://wiki.libsdl.org/SDL3/CategoryKeycode>
+<!--L-->
+[Category Locale]: <https://wiki.libsdl.org/SDL3/CategoryLocale>
+[Category Log]: https://wiki.libsdl.org/SDL3/CategoryLog
+<!--M-->
+[Category Main]: https://wiki.libsdl.org/SDL3/CategoryMain
+[Category Messagebox]: <https://wiki.libsdl.org/SDL3/CategoryMessagebox>
+[Category Metal]: <https://wiki.libsdl.org/SDL3/CategoryMetal>
+[Category Misc]: <https://wiki.libsdl.org/SDL3/CategoryMisc>
+[Category Mouse]: <https://wiki.libsdl.org/SDL3/CategoryMouse>
+[Category Mutex]: <https://wiki.libsdl.org/SDL3/CategoryMutex>
+<!--N-->
+<!--O-->
+<!--P-->
+[Category Pen]: <https://wiki.libsdl.org/SDL3/CategoryPen>
+[Category Pixels]: <https://wiki.libsdl.org/SDL3/CategoryPixels>
+[Category Platform]: <https://wiki.libsdl.org/SDL3/CategoryPlatform>
+[Category Power]: <https://wiki.libsdl.org/SDL3/CategoryPower>
+[Category Process]: <https://wiki.libsdl.org/SDL3/CategoryProcess>
+[Category Properties]: https://wiki.libsdl.org/SDL3/CategoryProperties
+<!--Q-->
+<!--R-->
+[Category Rect]: <https://wiki.libsdl.org/SDL3/CategoryRect>
+[Category Render]: <https://wiki.libsdl.org/SDL3/CategoryRender>
+<!--S-->
+[Category Scancode]: <https://wiki.libsdl.org/SDL3/CategoryScancode>
+[Category Sensor]: <https://wiki.libsdl.org/SDL3/CategorySensor>
+[Category Stdinc]: <https://wiki.libsdl.org/SDL3/CategoryStdinc>
+[Category Storage]: <https://wiki.libsdl.org/SDL3/CategoryStorage>
+[Category Surface]: <https://wiki.libsdl.org/SDL3/CategorySurface>
+[Category System]: <https://wiki.libsdl.org/SDL3/CategorySystem>
+<!--T-->
+[Category Thread]: <https://wiki.libsdl.org/SDL3/CategoryThread>
+[Category Time]: <https://wiki.libsdl.org/SDL3/CategoryTime>
+[Category Timer]: <https://wiki.libsdl.org/SDL3/CategoryTimer>
+[Category Touch]: <https://wiki.libsdl.org/SDL3/CategoryTouch>
+[Category Tray]: <https://wiki.libsdl.org/SDL3/CategoryTray>
+<!--U-->
+<!--V-->
+[Category Version]: https://wiki.libsdl.org/SDL3/CategoryVersion
+[Category Video]: https://wiki.libsdl.org/SDL3/CategoryVideo
+[Category Vulkan]: <https://wiki.libsdl.org/SDL3/CategoryVulkan>
+<!--W-->
+<!--X-->
+<!--Y-->
+<!--Z-->