feat(examples): run tween on SDL OpenGL host

Author: jgranick

README.md

@@ -50,6 +50,17 @@ The development and release presets build the native examples. Run the compiler-
 
 The example preserves the fifteen easing tracks from Flight's TypeScript tween example and renders one deterministic frame in a terminal. Its portable calculation is TypeScript transpiled by the pinned `flight-compiler`; a small handwritten C++ host owns terminal output. See [`examples/README.md`](examples/README.md) for the source, generated output, regeneration command, and the current boundary around browser-backed examples.
 
+The same generated curves also have an interactive SDL/OpenGL ES host. Enable the optional SDL package and disable the
+unused Vulkan adapter, then run the native window:
+
+```sh
+cmake --preset development \
+  -DFLIGHT_CPP_BUILD_HOST_SDL=ON \
+  -DFLIGHT_CPP_BUILD_HOST_SDL_VULKAN=OFF
+cmake --build --preset development
+./out/cmake/development/examples/flight_cpp_tween_sdl_gl_example
+```
+
 Consumers can build it in-tree with `add_subdirectory`, or install it and use:
 
 ```cmake

docs/host-sdl.md

@@ -31,6 +31,15 @@ cmake --build --preset development
 ctest --preset development
 ```
 
+With examples enabled by the preset, the native tween example exercises the GL path end to end:
+
+```sh
+./out/cmake/development/examples/flight_cpp_tween_sdl_gl_example
+```
+
+It animates the fifteen easing curves emitted from `examples/tween/source/tween.ts`. Rendering uses only the OpenGL ES
+context and procedure loader exposed by `Flight::HostSdlGl`; it does not introduce an SDL renderer abstraction.
+
 Set `-DFLIGHT_CPP_BUILD_HOST_SDL_VULKAN=OFF` for an SDL and GL/WGPU build without Vulkan development files. Native
 dependency discovery and target selection belong to CMake, so an npm wrapper would only obscure the options and is
 not provided. Bazel continues to cover the dependency-free runtime; the optional SDL package currently has a CMake

examples/CMakeLists.txt

@@ -2,6 +2,12 @@ add_executable(flight_cpp_tween_example tween/tween_example.cpp)
 target_link_libraries(flight_cpp_tween_example PRIVATE Flight::Cpp)
 flight_cpp_set_project_warnings(flight_cpp_tween_example)
 
+if(TARGET Flight::HostSdlGl)
+  add_executable(flight_cpp_tween_sdl_gl_example tween/tween_sdl_gl_example.cpp)
+  target_link_libraries(flight_cpp_tween_sdl_gl_example PRIVATE Flight::HostSdlGl)
+  flight_cpp_set_project_warnings(flight_cpp_tween_sdl_gl_example)
+endif()
+
 if(BUILD_TESTING)
   add_test(NAME flight_cpp.example.tween COMMAND flight_cpp_tween_example)
 endif()

examples/README.md

@@ -14,6 +14,21 @@ cmake --build --preset development
 ./out/cmake/development/examples/flight_cpp_tween_example
 ```
 
+The SDL/OpenGL ES entry point renders all fifteen generated easing tracks in a native window. It uses the handwritten
+SDL host for the window, event loop, GL context, procedure loading, and presentation; the curve calculations still
+come from the transpiled TypeScript above. Configure the optional host without requiring Vulkan, then run it:
+
+```sh
+cmake --preset development \
+  -DFLIGHT_CPP_BUILD_HOST_SDL=ON \
+  -DFLIGHT_CPP_BUILD_HOST_SDL_VULKAN=OFF
+cmake --build --preset development
+./out/cmake/development/examples/flight_cpp_tween_sdl_gl_example
+```
+
+Close the window or press Escape to exit. The executable also accepts `--smoke`, which creates a hidden GL window,
+renders three frames, and exits; this is useful with an offscreen SDL video driver in automated environments.
+
 To regenerate `tween/generated/tween.hpp` with the compiler revision pinned by this repository:
 
 ```sh
@@ -26,4 +41,9 @@ npm --prefix .dependencies/flight-compiler run compile -- \
   --package @flighthq/examples-tween
 ```
 
-The upstream browser entry point itself cannot currently be transpiled. It contains executable module-level statements and browser host calls; the pinned compiler refuses those statements rather than emitting invalid C++. The portable source also spells the elastic curve's phase shift as the equivalent `period / 4`, because the compiler currently emits `Math.asin` with an invalid C++ qualifier. Keeping the curve calculation in a separate source module makes both supported compiler boundaries visible and gives later compiler revisions a straightforward place to remove the adaptations.
+The upstream browser entry point itself cannot currently be transpiled. It contains executable module-level statements
+and browser host calls; the pinned compiler refuses those statements rather than emitting invalid C++. The portable
+source also spells the elastic curve's phase shift as the equivalent `period / 4`, because the compiler currently
+emits `Math.asin` with an invalid C++ qualifier. Keeping the curve calculation in a separate source module makes both
+supported compiler boundaries visible and gives later compiler revisions a straightforward place to remove the
+adaptations.

examples/tween/tween_sdl_gl_example.cpp

@@ -0,0 +1,209 @@
+#include "generated/tween.hpp"
+
+#include <flight/host_sdl/gl.hpp>
+#include <flight/host_sdl/host.hpp>
+#include <flight/host_sdl/window.hpp>
+
+#include <SDL3/SDL_keycode.h>
+#include <SDL3/SDL_opengles2.h>
+
+#include <algorithm>
+#include <array>
+#include <chrono>
+#include <cmath>
+#include <cstddef>
+#include <exception>
+#include <iostream>
+#include <stdexcept>
+#include <string_view>
+#include <thread>
+#include <type_traits>
+
+namespace {
+
+struct Color {
+  GLfloat red;
+  GLfloat green;
+  GLfloat blue;
+};
+
+template <typename Function>
+Function load_gl_function(const flight::host_sdl::GlContext& context, std::string_view name) {
+  static_assert(std::is_pointer_v<Function>);
+  return reinterpret_cast<Function>(context.function_address(name));
+}
+
+class GlFunctions final {
+ public:
+  explicit GlFunctions(const flight::host_sdl::GlContext& context)
+      : clear(load_gl_function<PFNGLCLEARPROC>(context, "glClear")),
+        clear_color(load_gl_function<PFNGLCLEARCOLORPROC>(context, "glClearColor")),
+        disable(load_gl_function<PFNGLDISABLEPROC>(context, "glDisable")),
+        enable(load_gl_function<PFNGLENABLEPROC>(context, "glEnable")),
+        get_error(load_gl_function<PFNGLGETERRORPROC>(context, "glGetError")),
+        scissor(load_gl_function<PFNGLSCISSORPROC>(context, "glScissor")),
+        viewport(load_gl_function<PFNGLVIEWPORTPROC>(context, "glViewport")) {}
+
+  PFNGLCLEARPROC clear;
+  PFNGLCLEARCOLORPROC clear_color;
+  PFNGLDISABLEPROC disable;
+  PFNGLENABLEPROC enable;
+  PFNGLGETERRORPROC get_error;
+  PFNGLSCISSORPROC scissor;
+  PFNGLVIEWPORTPROC viewport;
+};
+
+void fill_rectangle(
+    const GlFunctions& gl,
+    flight::host_sdl::WindowSize viewport,
+    int x,
+    int y,
+    int width,
+    int height,
+    Color color) {
+  const int left = std::clamp(x, 0, viewport.width);
+  const int bottom = std::clamp(y, 0, viewport.height);
+  const int right = std::clamp(x + width, 0, viewport.width);
+  const int top = std::clamp(y + height, 0, viewport.height);
+  if (right <= left || top <= bottom) return;
+  gl.scissor(left, bottom, right - left, top - bottom);
+  gl.clear_color(color.red, color.green, color.blue, 1.0F);
+  gl.clear(GL_COLOR_BUFFER_BIT);
+}
+
+void fill_circle(
+    const GlFunctions& gl,
+    flight::host_sdl::WindowSize viewport,
+    int center_x,
+    int center_y,
+    int radius,
+    Color color) {
+  const int radius_squared = radius * radius;
+  for (int offset_y = -radius; offset_y <= radius; ++offset_y) {
+    const auto extent = static_cast<int>(
+        std::sqrt(static_cast<double>(radius_squared - (offset_y * offset_y))));
+    fill_rectangle(
+        gl,
+        viewport,
+        center_x - extent,
+        center_y + offset_y,
+        (extent * 2) + 1,
+        1,
+        color);
+  }
+}
+
+void draw_frame(
+    const GlFunctions& gl,
+    flight::host_sdl::WindowSize size,
+    double progress) {
+  constexpr Color background{0.035F, 0.047F, 0.075F};
+  constexpr Color track{0.16F, 0.19F, 0.25F};
+  constexpr std::array<Color, 15> colors{{
+      {0.96F, 0.38F, 0.38F},
+      {0.96F, 0.55F, 0.30F},
+      {0.96F, 0.72F, 0.28F},
+      {0.78F, 0.80F, 0.28F},
+      {0.53F, 0.82F, 0.34F},
+      {0.30F, 0.82F, 0.53F},
+      {0.25F, 0.80F, 0.72F},
+      {0.23F, 0.72F, 0.88F},
+      {0.30F, 0.58F, 0.96F},
+      {0.45F, 0.48F, 0.96F},
+      {0.62F, 0.42F, 0.94F},
+      {0.77F, 0.38F, 0.88F},
+      {0.90F, 0.36F, 0.72F},
+      {0.96F, 0.36F, 0.56F},
+      {0.96F, 0.42F, 0.44F},
+  }};
+
+  gl.viewport(0, 0, size.width, size.height);
+  gl.disable(GL_SCISSOR_TEST);
+  gl.clear_color(background.red, background.green, background.blue, 1.0F);
+  gl.clear(GL_COLOR_BUFFER_BIT);
+  gl.enable(GL_SCISSOR_TEST);
+
+  const auto values = flighthq_examples_tween::sample_tween_curves(progress);
+  if (values.size() != colors.size()) throw std::runtime_error("unexpected tween curve count");
+
+  const int horizontal_margin = std::max(28, size.width / 16);
+  const int vertical_margin = std::max(20, size.height / 24);
+  const int available_height = std::max(1, size.height - (vertical_margin * 2));
+  const int row_height = std::max(1, available_height / static_cast<int>(colors.size()));
+  const int radius = std::clamp(row_height / 4, 4, 12);
+  const int track_left = horizontal_margin + radius;
+  const int track_right = std::max(track_left, size.width - horizontal_margin - radius);
+  const int track_width = track_right - track_left;
+
+  for (std::size_t index = 0; index < colors.size(); ++index) {
+    const int center_y =
+        size.height - vertical_margin -
+        static_cast<int>((static_cast<double>(index) + 0.5) * static_cast<double>(row_height));
+    fill_rectangle(gl, size, track_left, center_y - 1, track_width, 3, track);
+    const double value = std::clamp(values[index], 0.0, 1.0);
+    const int center_x = track_left + static_cast<int>(std::lround(value * static_cast<double>(track_width)));
+    fill_circle(gl, size, center_x, center_y, radius, colors[index]);
+  }
+  gl.disable(GL_SCISSOR_TEST);
+  if (gl.get_error() != GL_NO_ERROR) throw std::runtime_error("OpenGL rejected the tween frame");
+}
+
+int run(bool smoke) {
+  using namespace std::chrono_literals;
+
+  flight::host_sdl::Host host;
+  flight::host_sdl::WindowOptions options;
+  options.title = "Flight tween - SDL + OpenGL ES";
+  options.width = 960;
+  options.height = 720;
+  options.graphics_api = flight::host_sdl::GraphicsApi::open_gl;
+  options.hidden = smoke;
+  options.open_gl.major_version = 2;
+  options.open_gl.minor_version = 0;
+  options.open_gl.profile = flight::host_sdl::OpenGlProfile::es;
+
+  flight::host_sdl::Window window(options);
+  flight::host_sdl::GlContext context(window);
+  context.make_current(window);
+  const GlFunctions gl(context);
+
+  const std::uint64_t started = flight::host_sdl::Host::ticks_nanoseconds();
+  std::size_t frames = 0;
+  bool running = true;
+  while (running) {
+    SDL_Event event{};
+    while (host.poll_event(event)) {
+      if (event.type == SDL_EVENT_QUIT ||
+          (event.type == SDL_EVENT_KEY_DOWN && event.key.key == SDLK_ESCAPE)) {
+        running = false;
+      }
+    }
+
+    const std::uint64_t elapsed = flight::host_sdl::Host::ticks_nanoseconds() - started;
+    const double seconds = static_cast<double>(elapsed) / 1'000'000'000.0;
+    const double cycle = std::fmod(seconds / 2.0, 2.0);
+    const double progress = cycle <= 1.0 ? cycle : 2.0 - cycle;
+    draw_frame(gl, window.pixel_size(), progress);
+    context.swap(window);
+
+    ++frames;
+    if (smoke && frames >= 3) running = false;
+    std::this_thread::sleep_for(8ms);
+  }
+  return 0;
+}
+
+} // namespace
+
+int main(int argc, char** argv) {
+  if (argc > 2 || (argc == 2 && std::string_view(argv[1]) != "--smoke")) {
+    std::cerr << "usage: flight_cpp_tween_sdl_gl_example [--smoke]\n";
+    return 2;
+  }
+  try {
+    return run(argc == 2);
+  } catch (const std::exception& error) {
+    std::cerr << "Flight SDL tween failed: " << error.what() << '\n';
+    return 1;
+  }
+}

scripts/buildHealth.mjs

@@ -82,7 +82,14 @@ const benchmarkSources = filesUnder(path.join(cppRoot, 'benchmarks'), isNativeSo
 for (const source of benchmarkSources) requireSourceInBothBuilds(source, 'benchmark source');
 
 const exampleSources = filesUnder(path.join(cppRoot, 'examples'), isNativeSource);
-for (const source of exampleSources) requireSourceInBothBuilds(source, 'example source');
+const hostSdlExampleSources = exampleSources.filter(
+  (filename) => path.basename(filename) === 'tween_sdl_gl_example.cpp',
+);
+const portableExampleSources = exampleSources.filter((filename) => !hostSdlExampleSources.includes(filename));
+for (const source of portableExampleSources) requireSourceInBothBuilds(source, 'example source');
+for (const source of hostSdlExampleSources) {
+  requireText(cmakeGraph, path.basename(source), `CMake SDL example source ${path.basename(source)}`);
+}
 
 if (presets.version !== 2 || presets.cmakeMinimumRequired?.major !== 3 || presets.cmakeMinimumRequired.minor !== 20) {
   failures.push('CMakePresets.json must remain usable with the declared CMake 3.20 floor');
@@ -119,7 +126,7 @@ if (failures.length > 0) {
 }
 
 process.stdout.write(
-  `C++ build metadata agrees across CMake and Bazel ${bazelVersion}: ${String(publicHeaders.length)} public headers, ${String(productionSources.length)} runtime source(s), ${String(executableTests.length)} executable test source(s), ${String(benchmarkSources.length)} benchmark source(s), and ${String(exampleSources.length)} example source(s); CMake additionally declares ${String(hostSdlSources.length)} optional SDL host source(s).\n`,
+  `C++ build metadata agrees across CMake and Bazel ${bazelVersion}: ${String(publicHeaders.length)} public headers, ${String(productionSources.length)} runtime source(s), ${String(executableTests.length)} executable test source(s), ${String(benchmarkSources.length)} benchmark source(s), and ${String(portableExampleSources.length)} portable example source(s); CMake additionally declares ${String(hostSdlSources.length)} optional SDL host source(s) and ${String(hostSdlExampleSources.length)} SDL example source(s).\n`,
 );
 
 function filesUnder(directory, include) {