rbsdl3 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2ca77af0dc7dcc36ad74a55ba2004c4259e114b4ba7ac6d0101f1ea3b18e1007
+  data.tar.gz: f23967120fbe3f7b16c28f77ceecd334ad7514a26cbe06c4ac061dbb1e8735dc
+SHA512:
+  metadata.gz: de75e9160dfeecbb13a7fe6381cf714af7e467fdaa4dafa3911a38c052f4915da88a48a5eab34f8c871abf831909aabfcdfd58403f5a0ee3d89e261a673d81cd
+  data.tar.gz: bc98624b5fc9540b64620179e4850425db7c7689ca2864805379c7e24ae0af2f84a7bcf622d3d9532b2a45de58d71d0332eae7ab1db59a1cf96ebc1b9a7dd8fb

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2025-12-31
+
+### Added
+- Added SDL3 bindings built on `Fiddle::Importer`. Supports runtime linking via `dlload`, allowing the user to choose the target dynamic library at runtime.
+- `require "rbsdl3"` makes the SDL3 core API available (functions, constants, structs, enums, etc.) by loading `rbsdl3/sdl` internally.
+- Added optional extension entry points: `require "rbsdl3/image"` for SDL_image APIs and `require "rbsdl3/ttf"` for SDL_ttf APIs (both assume the SDL3 core is loaded).
+- Added Ruby-side helpers that mirror a subset of SDL macros (C-style integer casts, FOURCC, version helpers, etc.).
+- Added a stub/annotation mechanism for missing symbols and unsupported APIs: unresolved symbols raise `NotImplementedError`, and selected APIs can be explicitly marked as `unsupported:`.
+
+### Notes
+- Dependencies: Ruby >= 3.1, fiddle ~> 1.1.7.
+- Due to Fiddle limitations, some APIs raise `NotImplementedError`.
+  - SDL examples: `SDL_vsnprintf()` / `SDL_vasprintf()` / `SDL_SetErrorV()` / `SDL_LogMessageV()` / `SDL_IOvprintf()` / `SDL_GUIDToString()` / `SDL_StringToGUID()` / `SDL_SetGPUBlendConstants()`
+  - SDL_ttf examples: `TTF_RenderText_*` / `TTF_RenderGlyph_*`

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present shinokaro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,114 @@
+# rbsdl3
+
+rbsdl3 is a binding library for using SDL3 from Ruby. In addition to SDL3 itself, it also covers APIs from related libraries such as SDL_image and SDL_ttf. SDL dynamic libraries (DLL/so/dylib) are loaded explicitly by the user at runtime.
+
+- SDL (official): https://www.libsdl.org/
+- SDL3 Documentation (SDL Wiki): https://wiki.libsdl.org/SDL3/FrontPage
+
+## Features
+
+- Built on Ruby’s standard library, Fiddle.
+- Provides Ruby-side constants and struct definitions before any dynamic libraries are loaded.
+- Once the dynamic libraries are loaded, SDL APIs are bound and can be called as methods.
+- If an API symbol is not available at bind time, execution still continues; the corresponding method is defined as a stub that raises `NotImplementedError` when called.
+- Bindings for related libraries can be added as needed, for example with `require "rbsdl3/image"`.
+
+## Scope
+
+- Target: SDL3
+- Related libraries: SDL_image / SDL_ttf (SDL_mixer will be supported after an official SDL_mixer release)
+
+API coverage is not complete; some APIs may be unavailable.
+
+Some SDL constants currently assume little-endian values. Inline functions are not included.
+
+## Requirements
+
+rbsdl3 does not bundle SDL libraries. You must provide the SDL3 dynamic library (and, if you use them, the SDL_image / SDL_ttf dynamic libraries) separately.
+
+SDL dynamic libraries are loaded explicitly at runtime via `SDL3.dlload` (for each library you intend to use). The library names passed to `dlload` are examples and may differ by platform.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add rbsdl3
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install rbsdl3
+```
+
+## Usage
+
+### SDL3 (core)
+
+With `require "rbsdl3"`, Ruby-side definitions such as constants and structs are available. Calling functions requires `SDL3.dlload`.
+
+```ruby
+require "rbsdl3"
+SDL3::SDL_MAJOR_VERSION
+
+SDL3.SDL_GetVersion  #=> raises NoMethodError (not bound yet)
+
+SDL3.dlload("libSDL3")  # e.g.
+SDL3.SDL_GetVersion
+
+include SDL3
+SDL_GetVersion()
+```
+
+### Related libraries
+
+Related library bindings are added by requiring them individually.
+
+```ruby
+require "rbsdl3/image"
+SDL3::SDL_IMAGE_MAJOR_VERSION
+SDL3::SDL_MAJOR_VERSION
+
+SDL3.dlload("libSDL3_image")  # e.g.
+SDL3.IMG_Version
+SDL3.SDL_GetVersion
+
+include SDL3
+IMG_Version()
+SDL_GetVersion()
+```
+
+### Callbacks / function pointers
+
+```ruby
+require "rbsdl3"
+SDL3.bind(SDL3::SDL_HitTest) { |win, area, data| 0 }
+SDL3["SDL_HitTest"]
+```
+
+## Development
+
+c2ffi (https://github.com/rpav/c2ffi) is used as the source of the AST output from which most bindings are mechanically generated. Macros are extracted from header files using a custom extraction tool, and macro functions are also automatically converted. Anything that cannot be handled by these methods is bound manually.
+
+To fetch the latest SDL library releases used for generation, run:
+
+- `rake sources:checkout:all`
+
+The downloaded sources are stored under `tmp/` in the development directory.
+
+To generate the binding code from the fetched sources, run:
+
+- `rake bindings:generate:all`
+
+## Contributing
+
+Bug reports are welcome on GitHub at https://github.com/shinokaro/rbsdl3.
+
+If you find missing functions or macros, please open an issue with the corresponding SDL header/API details so they can be added.
+
+## License
+
+rbsdl3 is licensed under the MIT License.
+
+This project does not bundle SDL libraries. SDL3 and any related SDL_* libraries are separate projects and are distributed under their own licenses (zlib license).

data/lib/rbsdl3/image.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+require_relative "../rbsdl3"
+require_relative "sdl"
+
+module SDL3
+  using BindingsRefinement
+  SDL_image = proc {
+    # Ruby wrappers for SDL_image macros
+    #
+    const_set :SDL_IMAGE_MAJOR_VERSION, 3
+    const_set :SDL_IMAGE_MINOR_VERSION, 2
+    const_set :SDL_IMAGE_MICRO_VERSION, 4
+    const_set :SDL_IMAGE_VERSION, SDL_VERSIONNUM(SDL_IMAGE_MAJOR_VERSION, SDL_IMAGE_MINOR_VERSION, SDL_IMAGE_MICRO_VERSION)
+    module_function def SDL_IMAGE_VERSION_ATLEAST(x, y, z) = ((SDL_IMAGE_MAJOR_VERSION >= x) && (SDL_IMAGE_MAJOR_VERSION > x || SDL_IMAGE_MINOR_VERSION >= y) && (SDL_IMAGE_MAJOR_VERSION > x || SDL_IMAGE_MINOR_VERSION > y || SDL_IMAGE_MICRO_VERSION >= z))
+
+    # Fiddle declarations for SDL_image functions, structs, and enums
+    #
+    extern "int IMG_Version(void)"
+    extern "SDL_Surface * IMG_LoadTyped_IO(SDL_IOStream *, bool, char *)"
+    extern "SDL_Surface * IMG_Load(char *)"
+    extern "SDL_Surface * IMG_Load_IO(SDL_IOStream *, bool)"
+    extern "SDL_Texture * IMG_LoadTexture(SDL_Renderer *, char *)"
+    extern "SDL_Texture * IMG_LoadTexture_IO(SDL_Renderer *, SDL_IOStream *, bool)"
+    extern "SDL_Texture * IMG_LoadTextureTyped_IO(SDL_Renderer *, SDL_IOStream *, bool, char *)"
+    extern "bool IMG_isAVIF(SDL_IOStream *)"
+    extern "bool IMG_isICO(SDL_IOStream *)"
+    extern "bool IMG_isCUR(SDL_IOStream *)"
+    extern "bool IMG_isBMP(SDL_IOStream *)"
+    extern "bool IMG_isGIF(SDL_IOStream *)"
+    extern "bool IMG_isJPG(SDL_IOStream *)"
+    extern "bool IMG_isJXL(SDL_IOStream *)"
+    extern "bool IMG_isLBM(SDL_IOStream *)"
+    extern "bool IMG_isPCX(SDL_IOStream *)"
+    extern "bool IMG_isPNG(SDL_IOStream *)"
+    extern "bool IMG_isPNM(SDL_IOStream *)"
+    extern "bool IMG_isSVG(SDL_IOStream *)"
+    extern "bool IMG_isQOI(SDL_IOStream *)"
+    extern "bool IMG_isTIF(SDL_IOStream *)"
+    extern "bool IMG_isXCF(SDL_IOStream *)"
+    extern "bool IMG_isXPM(SDL_IOStream *)"
+    extern "bool IMG_isXV(SDL_IOStream *)"
+    extern "bool IMG_isWEBP(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadAVIF_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadICO_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadCUR_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadBMP_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadGIF_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadJPG_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadJXL_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadLBM_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadPCX_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadPNG_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadPNM_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadSVG_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadQOI_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadTGA_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadTIF_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadXCF_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadXPM_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadXV_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadWEBP_IO(SDL_IOStream *)"
+    extern "SDL_Surface * IMG_LoadSizedSVG_IO(SDL_IOStream *, int, int)"
+    extern "SDL_Surface * IMG_ReadXPMFromArray(char **)"
+    extern "SDL_Surface * IMG_ReadXPMFromArrayToRGB888(char **)"
+    extern "bool IMG_SaveAVIF(SDL_Surface *, char *, int)"
+    extern "bool IMG_SaveAVIF_IO(SDL_Surface *, SDL_IOStream *, bool, int)"
+    extern "bool IMG_SavePNG(SDL_Surface *, char *)"
+    extern "bool IMG_SavePNG_IO(SDL_Surface *, SDL_IOStream *, bool)"
+    extern "bool IMG_SaveJPG(SDL_Surface *, char *, int)"
+    extern "bool IMG_SaveJPG_IO(SDL_Surface *, SDL_IOStream *, bool, int)"
+    const_set :IMG_Animation, struct(
+      [
+        "int w",
+        "int h",
+        "int count",
+        "SDL_Surface **frames",
+        "int *delays",
+      ]
+    )
+    extern "IMG_Animation * IMG_LoadAnimation(char *)"
+    extern "IMG_Animation * IMG_LoadAnimation_IO(SDL_IOStream *, bool)"
+    extern "IMG_Animation * IMG_LoadAnimationTyped_IO(SDL_IOStream *, bool, char *)"
+    extern "void IMG_FreeAnimation(IMG_Animation *)"
+    extern "IMG_Animation * IMG_LoadGIFAnimation_IO(SDL_IOStream *)"
+    extern "IMG_Animation * IMG_LoadWEBPAnimation_IO(SDL_IOStream *)"
+  }
+  private_constant :SDL_image
+
+  SDL_image.call
+end