summaryrefslogtreecommitdiff
path: root/modules/webgl/c++
diff options
context:
space:
mode:
authorClaudius "keldu" Holeksa <mail@keldu.de>2026-11-13 14:12:49 +0100
committerClaudius "keldu" Holeksa <mail@keldu.de>2026-11-13 14:12:49 +0100
commite821d617802ebbfff756844e4d9720342fc78a4e (patch)
tree1dcf33b84698b5074218e44ea491b77a9c23ee66 /modules/webgl/c++
parent0c0087ef9482634273ec1a23d3a915754f94926d (diff)
downloadlibs-lbm-dev.tar.gz
Swarm POCdev
Diffstat (limited to 'modules/webgl/c++')
-rw-r--r--modules/webgl/c++/SConscript31
-rw-r--r--modules/webgl/c++/context.hpp112
-rw-r--r--modules/webgl/c++/probe.hpp321
-rw-r--r--modules/webgl/c++/toolchain_probe.cpp97
4 files changed, 561 insertions, 0 deletions
diff --git a/modules/webgl/c++/SConscript b/modules/webgl/c++/SConscript
new file mode 100644
index 0000000..d75d7e0
--- /dev/null
+++ b/modules/webgl/c++/SConscript
@@ -0,0 +1,31 @@
+#!/bin/false
+
+import os
+import os.path
+import glob
+
+
+Import('env')
+
+dir_path = Dir('.').abspath
+
+webgl_env = env.Clone();
+
+webgl_env.sources = sorted(glob.glob(dir_path + "/*.cpp"));
+webgl_env.headers = sorted(glob.glob(dir_path + "/*.hpp"));
+
+env.sources += webgl_env.sources;
+env.headers += webgl_env.headers;
+
+# The module is headers plus probe.cpp. toolchain_probe.cpp is the smoke test
+# target: it proves em++ can compile against the core and swarm headers and
+# that both the .js and the .wasm land where SCons expects them.
+objects = []
+webgl_env.add_source_files(objects, webgl_env.sources, shared=False);
+env.probe = webgl_env.em_program('#bin/kel_lbm_webgl_probe', [objects]);
+
+env.targets += [env.probe];
+
+env.Install('$prefix/include/kel/lbm/webgl/', webgl_env.headers);
+# Both the loader and the sidecar; the .js is useless without the .wasm.
+env.Install('$prefix/share/kel-lbm/webgl/', env.probe);
diff --git a/modules/webgl/c++/context.hpp b/modules/webgl/c++/context.hpp
new file mode 100644
index 0000000..2f04c16
--- /dev/null
+++ b/modules/webgl/c++/context.hpp
@@ -0,0 +1,112 @@
+#pragma once
+
+#include <emscripten/html5.h>
+#include <emscripten/html5_webgl.h>
+
+#include <GLES3/gl3.h>
+
+#include <string>
+
+/**
+ * Owning a WebGL2 context.
+ *
+ * The probe deliberately runs on its own throwaway context rather than the one
+ * the simulation will use. Measuring capacity means allocating until something
+ * breaks, and when a browser hits GPU exhaustion it frequently answers by
+ * killing the context rather than returning an error. Losing a context created
+ * for the purpose costs nothing; losing the one holding the lattice costs the
+ * run.
+ */
+namespace kel {
+namespace lbm {
+namespace webgl {
+
+class context {
+public:
+ context() = default;
+
+ context(const context &) = delete;
+ context &operator=(const context &) = delete;
+
+ ~context(){ destroy(); }
+
+ /**
+ * `target` is a CSS selector for the canvas, e.g. "#probe". In a worker
+ * this needs an OffscreenCanvas transferred from the main thread and the
+ * build flag to match; see the module's SConstruct.
+ */
+ bool create(const std::string &target){
+ destroy();
+
+ EmscriptenWebGLContextAttributes attrs;
+ emscripten_webgl_init_context_attributes(&attrs);
+
+ attrs.majorVersion = 2;
+ attrs.minorVersion = 0;
+
+ // None of this is drawn to. Turning the extras off keeps the context
+ // cheap and avoids the compositor holding buffers we never read.
+ attrs.alpha = EM_FALSE;
+ attrs.depth = EM_FALSE;
+ attrs.stencil = EM_FALSE;
+ attrs.antialias = EM_FALSE;
+
+ // Accept a software context rather than refusing one. A modest device
+ // should still be able to join: what it reports here is a memory
+ // budget, and that budget is real even when the renderer behind it is
+ // slow. The cost is that capacity alone cannot distinguish a software
+ // context from a fast one -- that is a throughput question, which is
+ // what the perf section of the capability is reserved for.
+ attrs.failIfMajorPerformanceCaveat = EM_FALSE;
+
+ handle_ = emscripten_webgl_create_context(target.c_str(), &attrs);
+ if(handle_ <= 0){
+ handle_ = 0;
+ return false;
+ }
+
+ if(emscripten_webgl_make_context_current(handle_) != EMSCRIPTEN_RESULT_SUCCESS){
+ destroy();
+ return false;
+ }
+
+ return true;
+ }
+
+ bool valid() const { return handle_ > 0; }
+
+ bool lost() const {
+ return handle_ > 0 and emscripten_is_webgl_context_lost(handle_);
+ }
+
+ /**
+ * Extensions have to be asked for by name before the entry points work,
+ * even where the underlying GLES symbol already exists.
+ */
+ bool enable_extension(const char *name){
+ if(handle_ <= 0){
+ return false;
+ }
+ return emscripten_webgl_enable_extension(handle_, name);
+ }
+
+ bool make_current(){
+ return handle_ > 0 and
+ emscripten_webgl_make_context_current(handle_)
+ == EMSCRIPTEN_RESULT_SUCCESS;
+ }
+
+ void destroy(){
+ if(handle_ > 0){
+ emscripten_webgl_destroy_context(handle_);
+ handle_ = 0;
+ }
+ }
+
+private:
+ EMSCRIPTEN_WEBGL_CONTEXT_HANDLE handle_ = 0;
+};
+
+} // namespace webgl
+} // namespace lbm
+} // namespace kel
diff --git a/modules/webgl/c++/probe.hpp b/modules/webgl/c++/probe.hpp
new file mode 100644
index 0000000..5dbc33c
--- /dev/null
+++ b/modules/webgl/c++/probe.hpp
@@ -0,0 +1,321 @@
+#pragma once
+
+#include "context.hpp"
+
+#include <kel/lbm/abstract/data.hpp>
+#include <kel/lbm/swarm/capability.hpp>
+#include <kel/lbm/swarm/capacity.hpp>
+#include <kel/lbm/swarm/probe_search.hpp>
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+/**
+ * Measuring what a browser will actually give you.
+ *
+ * Split in two on purpose. The limits and extensions are a handful of queries;
+ * the budget is a measurement, because WebGL2 has no capacity query and the
+ * limits it does report overstate the truth by around a hundredfold on a
+ * typical desktop.
+ *
+ * The strategy for that measurement is not here -- it is swarm's
+ * allocation_search, which is ordinary arithmetic and is unit tested. What
+ * lives here is only the part that genuinely needs a GPU: allocate, check,
+ * destroy. Everything in this header is unreachable without a browser, so the
+ * rule is that it stays thin enough to audit by reading.
+ *
+ * Header only, like core and swarm, so a wasm consumer needs no link wiring --
+ * which matters because em++ cannot consume nix buildInputs the way the native
+ * builds can.
+ */
+namespace kel {
+namespace lbm {
+namespace webgl {
+
+/// How a single allocation attempt ended. Not a bool, because "the context
+/// died" has to be distinguished from "that was too big".
+enum class trial_result {
+ ok,
+ /// Rejected, by a GL error or an incomplete framebuffer.
+ too_big,
+ /// The context went away. Everything after this is meaningless.
+ context_lost,
+};
+
+struct probe_config {
+ /// CSS selector for the throwaway canvas.
+ std::string canvas = "#kel-probe";
+
+ /// Distribution planes to allocate per attempt. Three is D2Q9.
+ uint32_t planes = 3u;
+
+ /// Both ping pong copies, since the real thing needs both resident.
+ uint32_t states = 2u;
+
+ /**
+ * Leaves room for the canvas, the compositor and other tabs. A guess,
+ * and flagged as one: it wants measuring against a real run on real
+ * hardware before it is trusted.
+ */
+ float safety_factor = 0.6f;
+};
+
+namespace impl {
+
+inline uint32_t get_int(GLenum name){
+ GLint value = 0;
+ glGetIntegerv(name, &value);
+ return (value > 0) ? static_cast<uint32_t>(value) : 0u;
+}
+
+/// Clears any error already pending, so the next check reports our own.
+inline void drain_errors(){
+ for(int i = 0; i < 16; ++i){
+ if(glGetError() == GL_NO_ERROR){
+ return;
+ }
+ }
+}
+
+} // namespace impl
+
+/// Fills the queryable limits. Requires a current context.
+inline void query_limits(data<sch::GlLimits> &out){
+ out.get<"max_texture_size">().set(impl::get_int(GL_MAX_TEXTURE_SIZE));
+ out.get<"max_3d_texture_size">().set(impl::get_int(GL_MAX_3D_TEXTURE_SIZE));
+ out.get<"max_array_texture_layers">().set(
+ impl::get_int(GL_MAX_ARRAY_TEXTURE_LAYERS));
+ out.get<"max_draw_buffers">().set(impl::get_int(GL_MAX_DRAW_BUFFERS));
+ out.get<"max_color_attachments">().set(impl::get_int(GL_MAX_COLOR_ATTACHMENTS));
+ out.get<"max_texture_image_units">().set(
+ impl::get_int(GL_MAX_TEXTURE_IMAGE_UNITS));
+ out.get<"max_combined_texture_image_units">().set(
+ impl::get_int(GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS));
+ out.get<"max_renderbuffer_size">().set(impl::get_int(GL_MAX_RENDERBUFFER_SIZE));
+ out.get<"max_fragment_uniform_vectors">().set(
+ impl::get_int(GL_MAX_FRAGMENT_UNIFORM_VECTORS));
+
+ GLint dims[2] = {0, 0};
+ glGetIntegerv(GL_MAX_VIEWPORT_DIMS, dims);
+ out.get<"max_viewport_dims">().at({{0u}}).set(
+ (dims[0] > 0) ? static_cast<uint32_t>(dims[0]) : 0u);
+ out.get<"max_viewport_dims">().at({{1u}}).set(
+ (dims[1] > 0) ? static_cast<uint32_t>(dims[1]) : 0u);
+}
+
+/// Fills the extension and context properties. Requires a current context.
+inline void query_features(context &ctx, data<sch::GlFeatures> &out){
+ out.get<"webgl2">().set(ctx.valid());
+
+ // Whether this is running off an OffscreenCanvas, which is what a worker
+ // thread needs in order to have a context at all.
+#if defined(__EMSCRIPTEN_PTHREADS__)
+ out.get<"offscreen_canvas">().set(true);
+#else
+ out.get<"offscreen_canvas">().set(false);
+#endif
+
+ // The hard gate. Without it, float textures are not colour renderable.
+ out.get<"color_buffer_float">().set(
+ ctx.enable_extension("EXT_color_buffer_float"));
+ out.get<"color_buffer_half_float">().set(
+ ctx.enable_extension("EXT_color_buffer_half_float"));
+
+ // Not needed by the solver, which fetches by texel rather than sampling.
+ // Reported because a smooth visualisation would want it.
+ out.get<"texture_float_linear">().set(
+ ctx.enable_extension("OES_texture_float_linear"));
+
+ // Will matter for immersed boundary force spreading, which accumulates by
+ // blending. Nothing uses it yet.
+ out.get<"float_blend">().set(ctx.enable_extension("EXT_float_blend"));
+
+ out.get<"parallel_shader_compile">().set(
+ ctx.enable_extension("KHR_parallel_shader_compile"));
+ out.get<"disjoint_timer_query">().set(
+ ctx.enable_extension("EXT_disjoint_timer_query_webgl2"));
+}
+
+/**
+ * One allocation attempt at `nx` by `ny`.
+ *
+ * Does the full sequence rather than just asking for memory: immutable storage,
+ * framebuffer completeness, and then a real clear plus a one texel readback.
+ * The last part is not ceremony -- a driver is entitled to defer the actual
+ * allocation until first use, so an attempt that stops at glTexStorage2D can
+ * report success against memory that does not exist.
+ */
+inline trial_result try_allocate(context &ctx, const probe_config &cfg,
+ uint32_t nx, uint32_t ny){
+ if(nx == 0u or ny == 0u){
+ return trial_result::too_big;
+ }
+
+ impl::drain_errors();
+
+ const uint32_t count = cfg.planes * cfg.states;
+
+ std::vector<GLuint> textures(count, 0u);
+ GLuint fbo = 0u;
+
+ // Every exit path goes through here. A probe that leaks on failure would
+ // poison the attempts that follow it, which is precisely the regime where
+ // failures are expected.
+ auto cleanup = [&](){
+ if(fbo != 0u){
+ glBindFramebuffer(GL_FRAMEBUFFER, 0);
+ glDeleteFramebuffers(1, &fbo);
+ }
+ for(GLuint tex : textures){
+ if(tex != 0u){
+ glDeleteTextures(1, &tex);
+ }
+ }
+ glFlush();
+ };
+
+ glGenTextures(static_cast<GLsizei>(count), textures.data());
+
+ for(uint32_t i = 0u; i < count; ++i){
+ glBindTexture(GL_TEXTURE_2D, textures[i]);
+
+ // Immutable storage. The mutable glTexImage2D path lets a driver defer
+ // the decision, so it can report success for memory it has not
+ // committed to.
+ glTexStorage2D(GL_TEXTURE_2D, 1, GL_RGBA32F,
+ static_cast<GLsizei>(nx), static_cast<GLsizei>(ny));
+
+ if(glGetError() != GL_NO_ERROR){
+ cleanup();
+ return ctx.lost() ? trial_result::context_lost : trial_result::too_big;
+ }
+
+ glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
+ glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
+ glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
+ glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
+ }
+
+ // Attach one state's worth, which is what a real pass renders into.
+ glGenFramebuffers(1, &fbo);
+ glBindFramebuffer(GL_FRAMEBUFFER, fbo);
+
+ std::vector<GLenum> attachments;
+ attachments.reserve(cfg.planes);
+ for(uint32_t i = 0u; i < cfg.planes; ++i){
+ glFramebufferTexture2D(GL_FRAMEBUFFER,
+ GL_COLOR_ATTACHMENT0 + i,
+ GL_TEXTURE_2D, textures[i], 0);
+ attachments.push_back(GL_COLOR_ATTACHMENT0 + i);
+ }
+ glDrawBuffers(static_cast<GLsizei>(attachments.size()), attachments.data());
+
+ if(glCheckFramebufferStatus(GL_FRAMEBUFFER) != GL_FRAMEBUFFER_COMPLETE){
+ cleanup();
+ return ctx.lost() ? trial_result::context_lost : trial_result::too_big;
+ }
+
+ // Force the driver to commit. Clearing touches every attachment, and the
+ // readback blocks until it has actually happened -- without this the whole
+ // sequence can succeed against memory that was never really allocated.
+ glViewport(0, 0, static_cast<GLsizei>(nx), static_cast<GLsizei>(ny));
+ glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
+ glClear(GL_COLOR_BUFFER_BIT);
+
+ float pixel[4] = {0.0f, 0.0f, 0.0f, 0.0f};
+ glReadBuffer(GL_COLOR_ATTACHMENT0);
+ glReadPixels(0, 0, 1, 1, GL_RGBA, GL_FLOAT, pixel);
+
+ const GLenum err = glGetError();
+ const bool was_lost = ctx.lost();
+
+ cleanup();
+
+ if(was_lost){
+ return trial_result::context_lost;
+ }
+ if(err != GL_NO_ERROR){
+ return trial_result::too_big;
+ }
+
+ return trial_result::ok;
+}
+
+/**
+ * Runs the whole probe on a throwaway context and fills the capability.
+ *
+ * Returns false if a WebGL2 context could not be had at all, or if
+ * EXT_color_buffer_float is missing -- without it a float texture is not
+ * colour renderable and there is no solver on this device, so there is nothing
+ * worth measuring. The capability is still filled in either case: an unusable
+ * worker is better reported than silent.
+ */
+inline bool probe_webgl2(const probe_config &cfg, data<sch::WebGl2Capability> &out){
+ context ctx;
+ if(not ctx.create(cfg.canvas)){
+ return false;
+ }
+
+ query_limits(out.get<"limits">());
+ query_features(ctx, out.get<"features">());
+
+ if(not out.get<"features">().get<"color_buffer_float">().get()){
+ return false;
+ }
+
+ const uint64_t max_tex = out.get<"limits">().get<"max_texture_size">().get();
+
+ const uint64_t bytes_per_cell =
+ swarm::packing_math::bytes_per_cell(9u, cfg.states, 1u, true);
+
+ swarm::allocation_search::config scfg;
+ scfg.ceiling_cells =
+ swarm::capacity_math::texture_bound_cells_2d(max_tex, 0u);
+
+ swarm::allocation_search search{scfg};
+
+ bool context_lost = false;
+ uint32_t trials = 0u;
+
+ while(not search.done()){
+ // Square-ish, so neither edge runs into max_texture_size before the
+ // area runs into memory.
+ const auto dom = swarm::capacity_math::fit_domain_2d(
+ search.candidate(), 1u, 1u, max_tex, 0u);
+
+ const trial_result result = try_allocate(
+ ctx, cfg, static_cast<uint32_t>(dom.nx),
+ static_cast<uint32_t>(dom.ny));
+
+ ++trials;
+
+ if(result == trial_result::context_lost){
+ // Browsers often answer GPU exhaustion by killing the context
+ // rather than returning an error. Everything after this would be
+ // meaningless, so stop and keep what was already measured.
+ context_lost = true;
+ break;
+ }
+
+ search.report(result == trial_result::ok);
+ }
+
+ const uint64_t best_bytes = search.best_cells() * bytes_per_cell;
+
+ auto &budget = out.get<"budget">();
+ budget.get<"probed_bytes_max">().set(best_bytes);
+ budget.get<"probed_bytes_safe">().set(
+ static_cast<uint64_t>(static_cast<double>(best_bytes) *
+ static_cast<double>(cfg.safety_factor)));
+ budget.get<"probe_trials">().set(trials);
+ budget.get<"context_lost_during_probe">().set(context_lost);
+ budget.get<"probe_hit_texture_size_bound">().set(search.hit_ceiling());
+ budget.get<"safety_factor">().set(cfg.safety_factor);
+
+ return not context_lost and search.best_cells() > 0u;
+}
+
+} // namespace webgl
+} // namespace lbm
+} // namespace kel
diff --git a/modules/webgl/c++/toolchain_probe.cpp b/modules/webgl/c++/toolchain_probe.cpp
new file mode 100644
index 0000000..f9e3907
--- /dev/null
+++ b/modules/webgl/c++/toolchain_probe.cpp
@@ -0,0 +1,97 @@
+/**
+ * The webgl module's smoke target.
+ *
+ * Nothing here can be meaningfully run without a browser, so its job is to make
+ * the compiler and linker check what a check phase cannot:
+ *
+ * 1. em++ finds the kel-lbm core and swarm headers. It is not a nix
+ * cc-wrapper, so it never reads NIX_CFLAGS_COMPILE and cannot pick up
+ * buildInputs; the include roots arrive through the kel_include scons
+ * variable instead.
+ * 2. The core headers are clean enough for a wasm target. descriptor.hpp is
+ * the narrow include the worker uses -- deliberately not
+ * <kel/lbm/lbm.hpp>, which drags in util.hpp's <sys/ioctl.h>, the vtk and
+ * csv writers and <iostream>.
+ * 3. Every GL and emscripten entry point the probe calls actually resolves.
+ * Emscripten sets ERROR_ON_UNDEFINED_SYMBOLS by default, so linking this
+ * is a real check on probe.cpp rather than a formality.
+ * 4. The chain the browser worker depends on composes end to end: probe a
+ * capability, put it in a hello, encode it to the text that goes on the
+ * data channel.
+ * 5. Both the .js loader and the .wasm sidecar are produced.
+ *
+ * The descriptor tables are consumed through a static_assert rather than merely
+ * included, so the compiler is forced to instantiate df_info and this cannot
+ * silently degrade into "the header parsed".
+ */
+
+#include "probe.hpp"
+
+#include <kel/lbm/descriptor.hpp>
+#include <kel/lbm/swarm/message.hpp>
+#include <kel/lbm/swarm/wire.hpp>
+
+#include <cstdint>
+#include <cstdio>
+#include <string>
+
+namespace {
+// Qualified rather than aliased: a local `sch` would collide with kel::lbm::sch
+// the moment main pulls kel::lbm into scope.
+using Desc = kel::lbm::sch::D2Q9;
+using dfi = kel::lbm::df_info<kel::lbm::sch::Float32, Desc>;
+
+static_assert(Desc::D == 2u, "D2Q9 has to be two dimensional");
+static_assert(Desc::Q == 9u, "D2Q9 has to carry nine directions");
+
+/**
+ * Opposites have to pair up. This is the cheapest property that actually
+ * touches the constexpr tables, which is the point -- it proves instantiation
+ * rather than parsing.
+ */
+constexpr bool opposites_pair(){
+ for(uint64_t i = 0u; i < Desc::Q; ++i){
+ if(dfi::opposite_index[dfi::opposite_index[i]] != i){
+ return false;
+ }
+ }
+ return true;
+}
+
+static_assert(opposites_pair(), "opposite_index has to be an involution");
+}
+
+int main(){
+ using namespace kel::lbm;
+
+ webgl::probe_config cfg;
+
+ // Without a canvas this returns false immediately, which is the correct
+ // behaviour and is all that can be checked outside a browser. The call is
+ // here so the signatures and the capability plumbing are compiled against.
+ data<sch::WebGl2Capability> gl{};
+ const bool usable = webgl::probe_webgl2(cfg, gl);
+
+ // The chain a real worker walks: capability into a hello, hello onto the
+ // wire. If this compiles and links, step six has no surprises waiting.
+ auto hello = swarm::make_message<sch::MsgHelloWebGl2>(
+ msg::hello, "probe", 0u);
+
+ auto &cap = hello.get<"capability">();
+ cap.get<"worker_id">().set(std::string{"probe"});
+ cap.get<"kind">().set(std::string{wkind::webgl2});
+ cap.get<"schema_version">().set(std::string{schema_version});
+ cap.get<"reported_at_ms">().set(0u);
+ cap.get<"user_agent">().set(std::string{"kel-lbm-webgl-probe"});
+ cap.get<"webgl2">() = gl;
+
+ auto eo_text = swarm::encode_message<sch::MsgHelloWebGl2>(hello);
+ if(eo_text.is_error()){
+ return 1;
+ }
+
+ std::printf("usable=%d hello=%zu bytes\n",
+ usable ? 1 : 0, eo_text.get_value().size());
+
+ return 0;
+}