sfml3-rb 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc41a984a71094455d29e95d4c529a1e228e5c5442333aca6eb57b9b7c9d3f5e
-  data.tar.gz: 835286043ece71ba5dc8c1790cdd6ab0370ae0924823771e03a811cd8acba1af
+  metadata.gz: f98dbb27451c7780e8dbd1ab1f677a9590d5d42b55db97cad407eee15fdd3ef8
+  data.tar.gz: 6ffe42d972c73f477b642ad6e1bfc1e9c4d5585f40bd9a9402bc08dfb03834ef
 SHA512:
-  metadata.gz: f75f7ce8244a36a0a8e93903ea0d323513753cfdf3e82f79364b3081a3d5ac651609897a0d4911c2509aac1e5107c37ab9ea9341eede85bb630a05228273ed3d
-  data.tar.gz: 68a989c7d4e1147cd5585bf8db85be15c3c1419bbefaeca95791fa37575900d8b841d1b33dd5009f9611e3b5a365b7410c7687ca8eecf96d188a05feb6de269f
+  metadata.gz: 7fde721522979c1446f14a18ce2433dcf6c8a1009c40cedb6771926f87a759bee9f44f338a47d8205336e51624ee80d919a18ea7172e9815c434194e814459c9
+  data.tar.gz: c2fde3b6034c72f50cf8d480a77bee01f79d505b510ca7b354c618bcf0f694307776d2409c00ab0b173253c3c797b2498e5f0c50cbd94256d902f7f96c816d91

data/.yardopts

@@ -0,0 +1,9 @@
+--markup markdown
+--output-dir doc
+--title sfml3-rb
+--readme README.md
+ext/**/*.c
+-
+CHANGELOG.md
+TODO.md
+LICENSE.md

data/CHANGELOG.md

@@ -6,26 +6,77 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-19
+
 ### Added
-* **Full YARD API documentation and RBS type signatures**, covering every
-  bound class, module, method and constant. Doc comments live in-place in
-  the `ext/**/*.c` sources (YARD's C parser, the same convention RDoc uses),
-  so they're published automatically to
-  [rubydoc.info](https://rubydoc.info/gems/sfml3-rb) on release; `rake yard`
-  builds them locally into `doc/`. `sig/**/*.rbs` ships in the gem alongside
-  the extension sources, for IDE completion (Solargraph, RubyMine) and
-  static type-checking (Sorbet, Steep). Run `rake rbs` to validate the
-  signatures.
+* **`SFML::WindowBase`, `SFML::RenderWindow` and the `SFML::RenderTarget` module**, mirroring
+  SFML 3's own hierarchy. `WindowBase` wraps `sfWindowBase` -- an OS window and event queue with
+  no OpenGL context -- and is constructible, with `Window` and `RenderWindow` derived from it.
+  `Window` keeps its existing `sfRenderWindow` behaviour; `RenderWindow` is the same renderable
+  window under the name that also includes `RenderTarget`. `RenderTexture` includes
+  `RenderTarget` too, so a drawable's `#draw` now accepts a `RenderWindow` or a `RenderTexture`
+  directly (the legacy `Target` still works). The shared window surface is generated once, in
+  `ext/window/window_base.inc`.
+* **RBS signatures are now checked against the code.** `sig/**/*.rbs` declares `SFML::VERSION`, and
+  a `Steepfile` plus the `steep` development gem add `rake steep` to type-check `lib/` against the
+  signatures. `check.yaml` runs both `rake rbs` and `rake steep`, on `main` and on `release/**`
+  PRs, which previously ran no workflow at all.
+
+### Changed
+* `Mouse.position`, `Mouse.set_position` and `Touch.position` dispatch to the
+  `*RenderWindow` or `*WindowBase` CSFML entry point depending on whether the argument is a
+  Window/RenderWindow or a WindowBase, instead of passing an `sfRenderWindow*` where an
+  `sfWindowBase*` is expected.
+* **RBS constructors use `def initialize`.** Every `def self.new` became
+  `def initialize: (…) -> void`, the form RubyMine links to `Foo.new` and Steep checks, and which
+  matches the C extension, where every constructor is an `initialize`.
 
-## [0.2.2]
+## [0.3.0] - 2026-09-19
+
+### Added
+* **Four more experimental binary-gem targets**: `aarch64-linux-musl`, `arm-linux-gnu`
+  (ARMv7 hard-float), `arm-linux-musl`, and `aarch64-mingw-ucrt` (64-bit Windows on ARM).
+  All four ride the same rake-compiler-dock cross-compilation this project already uses for
+  its other targets; none has been run on its target hardware yet, so all are
+  `experimental` in `publish.yaml` like `aarch64-linux-gnu`, `x86_64-darwin` and
+  `arm64-darwin` already were. `script/provision.sh` gained matching cases for the two new
+  glibc/musl Linux targets.
+* `rakelib/package.rake`'s `EXPECTED_ABIS` gained an entry for `aarch64-mingw-ucrt`: its
+  rake-compiler-dock image carries no cross Ruby older than 3.4, so that gem has no floor
+  below it — the same kind of upstream gap `x86-mingw32` already has at the top end.
+* `aarch64-linux-gnu` is now additionally run — not just cross-compiled — by a new
+  `test-arm64.yaml` workflow, on GitHub's hosted `ubuntu-24.04-arm` runner. It stays
+  `experimental` in `publish.yaml` for now; this is the evidence that will eventually
+  justify dropping that flag.
+* ARMv6 (32-bit), RISC-V (rv64gc), PowerPC (ppc64le), and any BSD are deliberately not
+  covered by a binary gem: rake-compiler-dock ships no cross-compilation image for any of
+  them, and building custom cross-toolchain infrastructure for them is a much larger,
+  separate undertaking. The source-gem fallback remains the only path there, unchanged.
 
 ### Fixed
-* **The macOS binary gems now build.** SFML 3.0.2 defaults
-  `CMAKE_OSX_DEPLOYMENT_TARGET` to 13.0, but the osxcross SDK in the
-  rake-compiler-dock image is 11.1 and rejects a newer target, so both Darwin
-  builds aborted while configuring SFML. The ports toolchain now pins the
-  deployment target to macOS 11.0, which is the floor Apple Silicon requires
-  anyway.
+* **A GC race in the audio bindings aborted the process on arm64.** `Sound`, `Music` and
+  `SoundStream` released the GVL inside their `dfree`, but their data types were marked
+  `RUBY_TYPED_FREE_IMMEDIATELY`, so the free could run *during* garbage collection: another
+  thread (Ruby's `Timeout` thread, in the test suite) could then allocate while GC was mid-cycle
+  and Ruby aborted with "object allocation during garbage collection phase". Dropping the flag
+  defers the free to a safe point; releasing the GVL is still what keeps `sf*_destroy` from
+  deadlocking against the audio thread.
+
+### Documentation
+* **Every public class, module, method and constant is documented**, with the
+  result rendered on [rubydoc.info](https://rubydoc.info/gems/sfml3-rb). The
+  comments live beside each binding in `ext/**/*.c`; `rake yard` builds them
+  into `doc/`. Previously the comments carried `call-seq` and `@return` tags
+  but little prose, so rubydoc.info showed a signature with a blank
+  description; every such method now has a sentence of its own.
+* RBS type signatures for the same surface ship in `sig/**/*.rbs`, for IDE
+  completion (Solargraph, RubyMine) and static checking (Sorbet, Steep);
+  `rake rbs` validates them.
+* `.yardopts` ships in the gem, so rubydoc.info generates with the same title,
+  README and extra files as `rake yard`.
+* `rake doc:undoc` fails when a method is left without a description, so the
+  coverage cannot regress silently (`yard stats` uses `blank?` and passes for
+  tag-only comments, which is how the blanks went unnoticed).
 
 ## [0.2.1]
 

data/README.md

@@ -2,17 +2,42 @@
 
 Ruby bindings for [SFML 3](https://www.sfml-dev.org/), via its C API, [CSFML](https://github.com/SFML/CSFML).
 
-## Status
-
-Latest release: **0.2.2**. Bound against **CSFML 3**. See [TODO.md](TODO.md) for which parts of the
-SFML 3 API are ported so far, and [CHANGELOG.md](CHANGELOG.md) for what changed recently.
-
-API docs (every class, module, method and constant) are on
-[rubydoc.info](https://rubydoc.info/gems/sfml3-rb). The gem also ships RBS type signatures
-(`sig/**/*.rbs`) alongside the extension sources, for IDE completion (Solargraph, RubyMine) and
-static type-checking (Sorbet, Steep).
-
-## Install
+[![Ruby](https://img.shields.io/badge/ruby-3.1%2B-red?style=flat-square)](https://www.ruby-lang.org/)
+[![Test](https://img.shields.io/github/actions/workflow/status/algaves/sfml3.rb/test.yaml?style=flat-square)](https://img.shields.io/github/actions/workflow/status/algaves/sfml3.rb/test.yaml?style=flat-square)
+[![Check](https://img.shields.io/github/actions/workflow/status/algaves/sfml3.rb/check.yaml?style=flat-square)](https://img.shields.io/github/actions/workflow/status/algaves/sfml3.rb/check.yaml?style=flat-square)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-4c9a2a?style=flat-square)](https://algaves.github.io/sfml3.rb/)
+[![Gem Version](https://img.shields.io/gem/v/sfml3-rb?style=flat-square)](https://rubygems.org/gems/sfml3-rb)
+[![Gem Downloads](https://img.shields.io/gem/dt/sfml3-rb?style=flat-square)](https://rubygems.org/gems/sfml3-rb)
+[![License](https://img.shields.io/badge/license-0BSD-green?style=flat-square)](LICENSE.md)
+
+Latest release: **0.3.1**, bound against **CSFML 3**.
+
+## Features
+
+* **Broad coverage of SFML 3**, bound through CSFML: windows and events, graphics, audio, network,
+  and the system layer, with every `sf*` entry point tracked in [TODO.md](TODO.md).
+* **Precompiled binary gems** for common platforms, with FreeType, SFML 3 and CSFML 3 statically
+  linked in — no toolchain and nothing to install system-wide.
+* **A source fallback everywhere else**, which downloads and builds the pinned, checksum-verified
+  dependencies at install time, so the gem works on macOS, ARM and the BSDs out of the box.
+* **Complete API documentation and types**: every class, module, method and constant is documented
+  on the [docs site](https://algaves.github.io/sfml3.rb/) and covered by RBS signatures shipped in
+  the gem.
+* **A close fit to SFML's own model**: classes mirror the C++ types (WindowBase, Window,
+  RenderWindow, Texture, Sprite, Sound, ...) minus the parts that only exist in C++, like
+  `std::string` and exceptions.
+
+## Table of Contents
+
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Documentation](#documentation)
+* [Development](#development)
+* [Contributing](#contributing)
+* [Acknowledgements](#acknowledgements)
+* [License](#license)
+
+## Installation
 
 ```sh
 gem install sfml3-rb
@@ -29,11 +54,18 @@ already linked in — no toolchain, no build, nothing to install system-wide:
 | `x86-linux-musl` | 3.1 – 4.0 | 32-bit musl |
 | `x64-mingw-ucrt` | 3.1 – 4.0 | 64-bit Windows, RubyInstaller 3.1+ |
 | `x86-mingw32` | 3.1 – **3.4** | 32-bit Windows |
-| `aarch64-linux-gnu`, `x86_64-darwin`, `arm64-darwin` | 3.1 – 4.0 | experimental, not yet built |
+| `aarch64-linux-gnu` | 3.1 – 4.0 | experimental, cross-built and run on a native arm64 CI runner |
+| `aarch64-linux-musl`, `arm-linux-gnu`, `arm-linux-musl` | 3.1 – 4.0 | experimental, not yet built |
+| `aarch64-mingw-ucrt` | 3.4 – **4.0** | experimental, 64-bit Windows on ARM |
+| `x86_64-darwin`, `arm64-darwin` | 3.1 – 4.0 | experimental, not yet built |
 
-Each gem carries one extension per Ruby ABI. Two gaps come from upstream rather than from this
-project: **RubyInstaller publishes no 32-bit Ruby 4.0**, so `x86-mingw32` stops at 3.4; and 64-bit
-Windows before Ruby 3.1 used a different platform (`x64-mingw32`), which is not built.
+Each gem carries one extension per Ruby ABI. Three gaps come from upstream rather than from this
+project: **RubyInstaller publishes no 32-bit Ruby 4.0**, so `x86-mingw32` stops at 3.4; 64-bit
+Windows before Ruby 3.1 used a different platform (`x64-mingw32`), which is not built; and the
+cross-compilation image for `aarch64-mingw-ucrt` carries no cross Ruby older than 3.4, so that
+gem has no floor below it.
+
+### Building from source
 
 Anywhere else — macOS, ARM, the BSDs — RubyGems falls back to the source gem, which downloads and
 builds FreeType, SFML 3 and CSFML 3 from pinned, checksum-verified tarballs at install time. That
@@ -42,36 +74,39 @@ takes a few minutes and needs:
 * Ruby >= 3.1
 * A C/C++ toolchain and CMake >= 3.22
 * On Linux, the X11/udev/OpenGL development headers SFML links against — these can't be bundled.
-  On Fedora:
 
-  ```sh
-  sudo dnf install cmake gcc-c++ libX11-devel \
-    libXrandr-devel libXcursor-devel libXi-devel systemd-devel libglvnd-devel
-  ```
+On Fedora:
+
+```sh
+sudo dnf install cmake gcc-c++ libX11-devel \
+  libXrandr-devel libXcursor-devel libXi-devel systemd-devel libglvnd-devel
+```
 
-  or on Debian/Ubuntu:
+On Debian/Ubuntu:
 
-  ```sh
-  sudo apt-get install cmake build-essential libx11-dev \
-    libxrandr-dev libxcursor-dev libxi-dev libudev-dev libgl1-mesa-dev
-  ```
+```sh
+sudo apt-get install cmake build-essential libx11-dev \
+  libxrandr-dev libxcursor-dev libxi-dev libudev-dev libgl1-mesa-dev
+```
 
 Each installed gem version builds its own copy; there's no build cache shared across versions.
 
+### Linking against system libraries
+
 To link against a system CSFML 3 instead (no download, no build):
 
 ```sh
 gem install sfml3-rb -- --enable-system-libraries
 ```
 
-## Usage
+## Quick Start
 
 ```ruby
 require 'sfml'
 include SFML
 
 window = Window.new VideoMode.new(640, 480, 32), 'SFML'
-event = Event.new
+event  = Event.new
 
 while window.is_open?
   while window.poll_event! event
@@ -83,7 +118,37 @@ while window.is_open?
 end
 ```
 
-See [`test/hello-world.rb`](test/hello-world.rb) for a fuller example with shapes and transforms.
+Event types are strings (`'closed'`, `'resized'`, `'key-pressed'`, ...); keys and buttons are enums.
+
+See [`test/hello-world.rb`](test/hello-world.rb) for a fuller example with shapes and transforms,
+and [`test/matrix-transformable.rb`](test/matrix-transformable.rb) for a visual demo. Neither is
+part of the test suite.
+
+## Documentation
+
+* [API reference](https://algaves.github.io/sfml3.rb/) — every class, module, method and constant,
+  built from the YARD comments in `ext/**/*.c` and deployed to GitHub Pages by CI. The same docs
+  are also generated on [RubyDoc.info](https://rubydoc.info/gems/sfml3-rb).
+* RBS type signatures (`sig/**/*.rbs`) describe the whole API, including the native classes, for
+  RBS-aware editors. `rake rbs` validates the signatures and `rake steep` type-checks `lib/`
+  against them.
+* [CHANGELOG.md](CHANGELOG.md) — what changed in each release.
+* [TODO.md](TODO.md) — module-by-module porting coverage and what is deliberately unbound.
+
+### IDE setup (RubyMine)
+
+`sig/**/*.rbs` is the only machine-readable description of the API: the native extension cannot be
+introspected, so an editor either reads the signatures or sees nothing. RBS support lives in
+**RubyMine** (and IntelliJ IDEA Ultimate with the Ruby plugin); CLion and other C/C++ IDEs show
+`.rbs` files as plain text.
+
+1. Open the project in RubyMine and point **Settings → Languages & Frameworks → Ruby SDK** at the
+   interpreter you build against (Ruby 3.1+). Keep the C sources in CLion/clangd.
+2. Run `bundle install` so the `rbs` gem (3.2+) is available to that interpreter.
+3. RubyMine indexes `sig/` automatically; completion, type info (`Ctrl+Shift+P`), parameter info
+   and *Navigate → Type Signature* then work for `Window.new` and the rest of the API.
+4. For a full type check, run `steep check` from *Run anything* (`Ctrl` twice); `Steepfile` points
+   it at `lib/` and `sig/`.
 
 ## Development
 
@@ -94,6 +159,7 @@ rake test     # compile, then run the test suite
 rake gem      # build the source gem into pkg/
 rake yard     # build API docs into doc/
 rake rbs      # validate sig/**/*.rbs
+rake steep    # type-check lib/ against sig/**/*.rbs
 ```
 
 `rake githooks:install` points your checkout at the committed `.githooks/` pre-commit hook, which
@@ -109,9 +175,12 @@ side by side: `core/` (CSFML umbrella header, macros, exceptions, UTF-32 convers
 devices), `graphics/` (shapes, Color, Transform, View, Texture, Text, Shader, the render targets),
 `audio/` and `network/`. Includes are subsystem-relative, e.g. `#include "graphics/circle.h"`.
 
-Two `.inc` files hold method bodies shared by several classes and are included once per class with
-a different macro prefix: `audio/sound_source.inc` (Sound, Music, SoundStream) and
-`graphics/render_target.inc` (Window, RenderTexture).
+Three `.inc` files hold method bodies shared by several classes and are included once per class
+with a different macro prefix: `audio/sound_source.inc` (Sound, Music, SoundStream),
+`window/window_base.inc` (WindowBase, Window) and `graphics/render_target.inc` (Window,
+RenderTexture). `SFML::RenderWindow < SFML::Window < SFML::WindowBase` and includes the
+`SFML::RenderTarget` module, so a drawable's `#draw` accepts a `RenderWindow` or a
+`RenderTexture` directly; `SFML::Target` remains as the legacy generic wrapper.
 
 Note that mkmf flattens object files to their basenames, so every `.c` filename has to stay
 unique across the whole tree — and that `$srcs` is baked into the generated Makefile, so after
@@ -138,9 +207,31 @@ mingw toolchain and the osxcross SDK already provide.
 Binary gems carry one extension per Ruby ABI under `lib/sfml/<major.minor>/`; `lib/sfml.rb` prefers
 that and falls back to the single `lib/sfml/sfml_ext.so` a source build installs.
 
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/algaves/sfml3.rb/issues). Before opening a pull request:
+
+```sh
+bundle install
+bundle exec rake test   # build the extension and run the suite
+bundle exec rubocop     # lint Ruby (CI enforces this)
+```
+
+Install the pre-commit hook with `bundle exec rake githooks:install` so staged Ruby is linted and
+staged C is formatted automatically. The C build is warning-clean under `SFML_STRICT=1`; keep it
+that way.
+
+## Acknowledgements
+
+This gem would not exist without [SFML](https://www.sfml-dev.org/) and its C binding,
+[CSFML](https://github.com/SFML/CSFML), both maintained by the SFML team. The source build also
+vendors and links FreeType, Ogg, Vorbis and FLAC; see [`ext/ports.rb`](ext/ports.rb) and the
+[LICENSE](LICENSE.md) for their terms.
+
 ## License
 
-[0BSD](LICENSE.md)
+This project is licensed under the BSD Zero Clause License (0BSD) - see the [LICENSE](LICENSE.md) file for details.
 
 ---
 

data/TODO.md

@@ -51,9 +51,14 @@ Base module: time, vectors, clocks, streams.
 
 OpenGL-based windows, events, input handling.
 
-- [x] **Window** — `SFML::Window` (`ext/window/window.c`); wraps `sfRenderWindow`, so this single
-      class covers what SFML splits into `WindowBase` + `Window` + `RenderWindow`. Accepts style,
-      state and `ContextSettings`; exposes min/max size, icon, cursor, native handle, settings.
+- [x] **WindowBase** — `SFML::WindowBase` (`ext/window/window_base.c`); wraps `sfWindowBase`, an OS
+      window and event queue with no OpenGL context. The methods shared with `Window` are generated
+      from `ext/window/window_base.inc`.
+- [x] **Window** — `SFML::Window` (`ext/window/window.c`); wraps `sfRenderWindow` and derives from
+      `WindowBase`, overriding every base method with the matching `sfRenderWindow_*` entry point.
+      Accepts style, state and `ContextSettings`; exposes min/max size, icon, cursor, native handle,
+      settings, display, and the render-target surface. Deliberately still renderable, so existing
+      `Window.new(...).clear` code keeps working.
 - [x] **VideoMode** — `SFML::VideoMode` (`ext/window/video_mode.c`); includes `desktop_mode` and
       `fullscreen_modes`
 - [x] **Event** — `SFML::Event` (`ext/window/event.c`, `ext/window/event_name.c`); every payload is
@@ -87,13 +92,16 @@ OpenGL-based windows, events, input handling.
 - [x] **Drawable** — `SFML::Drawable` mixin (`ext/graphics/drawable.c`)
 - [x] **RenderStates** — `SFML::RenderState` (`ext/graphics/render_state.c`); blend mode, stencil
       mode, coordinate type, texture, shader and transform are all settable
-- [x] **RenderTarget** — `SFML::Target` (`ext/graphics/target.c`) dispatches to `sfRenderWindow_*`
-      or `sfRenderTexture_*` at runtime for `Drawable#draw`. The methods each concrete target owns
-      directly — `map_pixel_to_coords`, `map_coords_to_pixel`, `push_gl_states`, `pop_gl_states`,
+- [x] **RenderTarget** — `SFML::RenderTarget` module (`ext/graphics/target.c`), included by
+      `RenderWindow` and `RenderTexture`, so a drawable's `#draw` accepts either directly. The
+      methods — `map_pixel_to_coords`, `map_coords_to_pixel`, `push_gl_states`, `pop_gl_states`,
       `reset_gl_states`, `draw_primitives`, `draw_vertex_buffer_range`, `clear_stencil`,
       `clear_color_and_stencil`, `viewport`, `scissor`, `srgb?` — are generated once for both
-      `Window` and `RenderTexture` from `ext/graphics/render_target.inc`
-- [x] **RenderWindow** — folded into `SFML::Window` (see Window module above)
+      `Window` and `RenderTexture` from `ext/graphics/render_target.inc`. `SFML::Target` remains
+      as the legacy runtime-dispatch wrapper for `Drawable#draw`.
+- [x] **RenderWindow** — `SFML::RenderWindow` (`ext/graphics/render_window.c`); derives from
+      `Window` and includes `RenderTarget`. Creation, events and the window surface come from
+      `Window` / `WindowBase`.
 - [x] **RenderTexture** — `SFML::RenderTexture` (`ext/graphics/render_texture.c`)
 - [x] **View** — `SFML::View` (`ext/graphics/view.c`); including `View.from_rect` and
       `scissor`/`scissor=`
@@ -179,9 +187,8 @@ without re-deriving the reasoning each time.
 
 | Symbols | Why |
 | --- | --- |
-| `sfWindow_*`, `sfWindowBase_*` (~55 functions) | `SFML::Window` wraps `sfRenderWindow`, which subsumes both a plain window and a base window. |
-| `sfMouse_*WindowBase`, `sfTouch_getPositionWindowBase` | Superseded by the `*RenderWindow` forms, which need no downcast. |
-| `sfRenderWindow_create`, `sfText_getString`/`setString`, `sfRenderWindow_setTitle`, `sfFtpDirectoryResponse_getDirectory` | Superseded by their `*Unicode` counterparts; the narrow forms decode through the C locale and mangle non-ASCII. |
+| `sfWindow_*` (~26 functions) | A plain `sfWindow` (an OpenGL context with no render-target surface); `SFML::Window` wraps `sfRenderWindow` and `SFML::WindowBase` wraps `sfWindowBase`. |
+| `sfRenderWindow_create`, `sfWindowBase_create`, `sfText_getString`/`setString`, `sfRenderWindow_setTitle`, `sfWindowBase_setTitle`, `sfFtpDirectoryResponse_getDirectory` | Superseded by their `*Unicode` counterparts; the narrow forms decode through the C locale and mangle non-ASCII. |
 | `sfColor_add`/`subtract`/`modulate`/`fromRGB`/`fromRGBA`/`fromInteger`/`toInteger`, `sfIntRect_contains`/`intersects` | Reimplemented directly in C in `color.c` / `rect.c`; the Ruby methods exist. |
 | `sfSprite_getTexture`, `sfText_getFont`, `sf*Shape_getTexture` | The Ruby getters return the cached wrapper object. CSFML returns a non-owning pointer, so re-wrapping it would hand Ruby an object it must not free. |
 | `sfShape_getPoint`, `sfShape_getPointCount` | `SFML::Shape` reads these from the Ruby subclass, which is where they are defined. |

data/ext/audio/audio_enums.c

@@ -3,12 +3,12 @@
 #include <ruby.h>
 #include <string.h>
 
-static const char *sound_status_names[] = {"stopped", "paused", "playing"};
+static const char* sound_status_names[] = {"stopped", "paused", "playing"};
 
 /* Designated initializers, indexed by the enum constant rather than by
    position: CSFML 3 defines the channel order, and a positional table would
    silently return the wrong name if a future release inserted a value. */
-static const char *sound_channel_names[] = {
+static const char* sound_channel_names[] = {
     [sfSoundChannelUnspecified] = "unspecified",
     [sfSoundChannelMono] = "mono",
     [sfSoundChannelFrontLeft] = "front_left",
@@ -28,11 +28,10 @@ static const char *sound_channel_names[] = {
     [sfSoundChannelTopFrontCenter] = "top_front_center",
     [sfSoundChannelTopBackLeft] = "top_back_left",
     [sfSoundChannelTopBackRight] = "top_back_right",
-    [sfSoundChannelTopBackCenter] = "top_back_center"
-};
+    [sfSoundChannelTopBackCenter] = "top_back_center"};
 
-static int symbol_index(VALUE rb_symbol, const char *const *names, size_t count) {
-    const char *name;
+static int symbol_index(VALUE rb_symbol, const char* const* names, size_t count) {
+    const char* name;
     size_t i;
 
     if (!SYMBOL_P(rb_symbol)) {
@@ -43,14 +42,14 @@ static int symbol_index(VALUE rb_symbol, const char *const *names, size_t count)
 
     for (i = 0; i < count; i++) {
         if (names[i] != NULL && strcmp(name, names[i]) == 0) {
-            return (int) i;
+            return (int)i;
         }
     }
 
     return -1;
 }
 
-const char *sound_status_name(sfSoundStatus status) {
+const char* sound_status_name(sfSoundStatus status) {
     if (status >= sfStopped && status <= sfPlaying) {
         return sound_status_names[status];
     }
@@ -62,7 +61,7 @@ sfSoundStatus sound_status_from_rb(VALUE rb_status) {
     int index;
 
     if (RB_INTEGER_TYPE_P(rb_status)) {
-        return (sfSoundStatus) NUM2INT(rb_status);
+        return (sfSoundStatus)NUM2INT(rb_status);
     }
 
     index = symbol_index(rb_status, sound_status_names, 3);
@@ -71,10 +70,10 @@ sfSoundStatus sound_status_from_rb(VALUE rb_status) {
         rb_raise(rb_eArgError, "unknown sound status");
     }
 
-    return (sfSoundStatus) index;
+    return (sfSoundStatus)index;
 }
 
-const char *sound_channel_name(sfSoundChannel channel) {
+const char* sound_channel_name(sfSoundChannel channel) {
     if (channel >= sfSoundChannelUnspecified && channel <= sfSoundChannelTopBackCenter &&
         sound_channel_names[channel] != NULL) {
         return sound_channel_names[channel];
@@ -87,7 +86,7 @@ sfSoundChannel sound_channel_from_rb(VALUE rb_channel) {
     int index;
 
     if (RB_INTEGER_TYPE_P(rb_channel)) {
-        return (sfSoundChannel) NUM2INT(rb_channel);
+        return (sfSoundChannel)NUM2INT(rb_channel);
     }
 
     index = symbol_index(rb_channel, sound_channel_names,
@@ -97,35 +96,74 @@ sfSoundChannel sound_channel_from_rb(VALUE rb_channel) {
         rb_raise(rb_eArgError, "unknown sound channel");
     }
 
-    return (sfSoundChannel) index;
+    return (sfSoundChannel)index;
 }
 
-void Init_AudioEnums(VALUE rb_module) {
-    VALUE rb_mSoundStatus = rb_define_module_under(rb_module, "SoundStatus");
-    VALUE rb_mSoundChannel = rb_define_module_under(rb_module, "SoundChannel");
-
+/* Document-module: SFML::SoundStatus
+ * Playback state constants returned by SoundSource#status (Sound, Music,
+ * SoundStream). Mirrored as symbols (+:stopped+, +:paused+, +:playing+) by
+ * that method rather than these Integer constants, but both refer to the
+ * same underlying values.
+ */
+
+/* Document-module: SFML::SoundChannel
+ * Speaker position constants used in a channel map (SoundBuffer#channel_map,
+ * Music#channel_map, SoundStream#channel_map, SoundRecorder#channel_map),
+ * mirrored as symbols (e.g. +:front_left+) rather than these Integer
+ * constants in those methods.
+ */
+void Init_AudioEnums(VALUE rb_mSFML) {
+    VALUE rb_mSoundStatus = rb_define_module_under(rb_mSFML, "SoundStatus");
+    VALUE rb_mSoundChannel = rb_define_module_under(rb_mSFML, "SoundChannel");
+
+    /* The source is not playing. */
     rb_define_const(rb_mSoundStatus, "STOPPED", INT2NUM(sfStopped));
+    /* The source is paused; #playing_offset stays where it was paused. */
     rb_define_const(rb_mSoundStatus, "PAUSED", INT2NUM(sfPaused));
+    /* The source is currently playing. */
     rb_define_const(rb_mSoundStatus, "PLAYING", INT2NUM(sfPlaying));
 
+    /* No channel position specified. */
     rb_define_const(rb_mSoundChannel, "UNSPECIFIED", INT2NUM(sfSoundChannelUnspecified));
+    /* A single, centered channel. */
     rb_define_const(rb_mSoundChannel, "MONO", INT2NUM(sfSoundChannelMono));
+    /* Front left speaker. */
     rb_define_const(rb_mSoundChannel, "FRONT_LEFT", INT2NUM(sfSoundChannelFrontLeft));
+    /* Front right speaker. */
     rb_define_const(rb_mSoundChannel, "FRONT_RIGHT", INT2NUM(sfSoundChannelFrontRight));
+    /* Front center speaker. */
     rb_define_const(rb_mSoundChannel, "FRONT_CENTER", INT2NUM(sfSoundChannelFrontCenter));
-    rb_define_const(rb_mSoundChannel, "FRONT_LEFT_OF_CENTER", INT2NUM(sfSoundChannelFrontLeftOfCenter));
-    rb_define_const(rb_mSoundChannel, "FRONT_RIGHT_OF_CENTER", INT2NUM(sfSoundChannelFrontRightOfCenter));
-    rb_define_const(rb_mSoundChannel, "LOW_FREQUENCY_EFFECTS", INT2NUM(sfSoundChannelLowFrequencyEffects));
+    /* Front left-of-center speaker. */
+    rb_define_const(rb_mSoundChannel, "FRONT_LEFT_OF_CENTER",
+                    INT2NUM(sfSoundChannelFrontLeftOfCenter));
+    /* Front right-of-center speaker. */
+    rb_define_const(rb_mSoundChannel, "FRONT_RIGHT_OF_CENTER",
+                    INT2NUM(sfSoundChannelFrontRightOfCenter));
+    /* Low-frequency effects (subwoofer) channel. */
+    rb_define_const(rb_mSoundChannel, "LOW_FREQUENCY_EFFECTS",
+                    INT2NUM(sfSoundChannelLowFrequencyEffects));
+    /* Back left speaker. */
     rb_define_const(rb_mSoundChannel, "BACK_LEFT", INT2NUM(sfSoundChannelBackLeft));
+    /* Back right speaker. */
     rb_define_const(rb_mSoundChannel, "BACK_RIGHT", INT2NUM(sfSoundChannelBackRight));
+    /* Back center speaker. */
     rb_define_const(rb_mSoundChannel, "BACK_CENTER", INT2NUM(sfSoundChannelBackCenter));
+    /* Side left speaker. */
     rb_define_const(rb_mSoundChannel, "SIDE_LEFT", INT2NUM(sfSoundChannelSideLeft));
+    /* Side right speaker. */
     rb_define_const(rb_mSoundChannel, "SIDE_RIGHT", INT2NUM(sfSoundChannelSideRight));
+    /* Top center speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_CENTER", INT2NUM(sfSoundChannelTopCenter));
+    /* Top front left speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_FRONT_LEFT", INT2NUM(sfSoundChannelTopFrontLeft));
+    /* Top front right speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_FRONT_RIGHT", INT2NUM(sfSoundChannelTopFrontRight));
+    /* Top front center speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_FRONT_CENTER", INT2NUM(sfSoundChannelTopFrontCenter));
+    /* Top back left speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_BACK_LEFT", INT2NUM(sfSoundChannelTopBackLeft));
+    /* Top back right speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_BACK_RIGHT", INT2NUM(sfSoundChannelTopBackRight));
+    /* Top back center speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_BACK_CENTER", INT2NUM(sfSoundChannelTopBackCenter));
 }