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

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 Bliting 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, then those respective pages are used to fill in the rest of the checklist.

In progress/complete:

• By category:
• BASICS
  • [~] Category Video
    • hdk::sdl::Window
    • hdk::sdl::Display
  • Category Surface
    • hdk::sdl::Surface
  • Category Main
  • Category Init
  • Category Hints
  • 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