Skip to content

Add opt-in Emscripten WebGL/OffscreenCanvas support - #505

Open
Alex-PLACET wants to merge 1 commit into
compiler-research:mainfrom
Alex-PLACET:feature/emscripten-webgl-offscreen
Open

Alex-PLACET wants to merge 1 commit into
compiler-research:mainfrom
Alex-PLACET:feature/emscripten-webgl-offscreen

Conversation

@Alex-PLACET

@Alex-PLACET Alex-PLACET commented Nov 5, 2026 •

Copy link
Copy Markdown

Description

Add XEUS_CPP_EMSCRIPTEN_WEBGL (OFF by default) to build the xcpp kernel with WebGL2 and OffscreenCanvas support. The option enables the Emscripten WebGL2/OffscreenCanvas link flags, keeps the existing exported runtime methods, and adds GL so transferred OffscreenCanvas objects are available through Module.GL.offscreenCanvases.

Wire the option into the wasm CI build and verify that the generated xcpp.js exports Module.GL and offscreenCanvases. Document the option in the wasm build instructions and build-options reference.

Screencast_20261105_142518 Thanks to this modification, we are able to display and interact with WebGL canvas in JupyterLite content (using webworkers). Here it's only WebGL code/shader, but I'm working on GUI libraries, like SDL, too

Type of change

Please tick all options which are relevant.

  • Bug fix
  • New feature
  • Added/removed dependencies
  • Required documentation updates

@Alex-PLACET
Alex-PLACET marked this pull request as ready for review November 5, 2026 13:03
@anutosh491

anutosh491 commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

Woah sounds pretty cool !

Shall go through it soon.

Comment thread CMakeLists.txt Resolved
@codecov-commenter

codecov-commenter commented Nov 5, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.70%. Comparing base (2be8b64) to head (bac15fa).

Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff           @@
##             main     #505   +/-   ##
=======================================
  Coverage   72.70%   72.70%           
=======================================
  Files          18       18           
  Lines        1209     1209           
  Branches      115      115           
=======================================
  Hits          879      879           
  Misses        330      330           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@Alex-PLACET

Alex-PLACET commented Nov 5, 2026 •

Copy link
Copy Markdown
Author

Comment thread .github/workflows/main.yml Resolved
Comment thread docs/source/InstallationAndUsage.rst Resolved
Comment thread CMakeLists.txt Resolved
Comment thread CMakeLists.txt Resolved
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@Alex-PLACET
Alex-PLACET requested a review from mcbarton November 6, 2026 14:04
@anutosh491

Copy link
Copy Markdown
Collaborator

I think I like most of what I see here. Maybe one thing that comes to my mind is that we can add a cool demo for people to try out here https://github.com/compiler-research/xeus-cpp/tree/main/notebooks

Maybe we can just add it in the lite demo if it's just a cell or two.

@Alex-PLACET

Alex-PLACET commented Nov 9, 2026 •

Copy link
Copy Markdown
Author

Here a link to show simple WebGL canva and log the events: https://alex-placet.github.io/canvas-host/lab/index.html
Behind, it uses the canva-host library which do a lot of glue.

@mcbarton

Copy link
Copy Markdown
Collaborator

Here a link to show simple WebGL canva and log the events: https://alex-placet.github.io/canvas-host/lab/index.html Behind, it uses the canva-host library which do a lot of glue.

If we include this notebook in the PR, we would need the webgl turned on in the Github deployment, and the read the docs PR preview build.

Comment thread .github/workflows/main.yml Resolved
@anutosh491

Copy link
Copy Markdown
Collaborator

If we include this notebook in the PR, we would need the webgl turned on in the Github deployment, and the read the docs PR preview build.

Ahh let it be if it's too hard to get that.

@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

2 similar comments
@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@Alex-PLACET
Alex-PLACET requested a review from mcbarton November 10, 2026 14:55
@anutosh491

Copy link
Copy Markdown
Collaborator

I think this is taking good shape now. We should be able to finish merging Matthew's pr with the emsdk update by tomorrow and then land this I guess!

@mcbarton mcbarton left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comments for why I am requesting changes. Also if we absolutely need the option XEUS_CPP_EMSCRIPTEN_WEBGL then it needs including in the deployment workflow, and the read the docs PR preview.

Comment thread .github/workflows/main.yml Resolved
Comment thread .github/workflows/main.yml Resolved
Comment thread test/CMakeLists.txt Resolved
Comment thread README.md Resolved
Comment thread test/test_webgl.cpp Resolved
@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

Comment thread .github/workflows/main.yml Resolved
Comment thread .github/workflows/main.yml Resolved
Comment thread .github/workflows/main.yml Resolved
@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@mcbarton

mcbarton commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

@anutosh491 I ask that you do not approve the workflow to run anymore times until #505 (comment) is addressed. The PR is taking the wrong approach, my review comments are being ignored and I do not appreciate you ignoring my comments either by approving the workflow to run.

@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@Alex-PLACET

Alex-PLACET commented Nov 12, 2026 •

Copy link
Copy Markdown
Author

@mcbarton I don't ignore your comments, I'm iterating on the code and try to have green CI builds. I re-request your review only when the PR is in a good shape to avoid to waste your time.
I just pushed a commit to remove xvfb, let's see if it works on linux machine without display.
edit: It doesn't work: https://github.com/compiler-research/xeus-cpp/actions/runs/43225801132/job/131209117108?pr=505#step:6:4416

@mcbarton

mcbarton commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

@mcbarton I don't ignore your comments, I'm iterating on the code and try to have green CI builds. I re-request your review only when the PR is in a good shape to avoid to waste your time. I just pushed a commit to remove xvfb, let's see if it works on linux machine without display. edit: It doesn't work: https://github.com/compiler-research/xeus-cpp/actions/runs/43225801132/job/131209117108?pr=505#step:6:4416

I'm away from my computer at the moment to try it out, but I suggest you install ubuntu desktop on the Github runner to see if it then has a display (and see how long it takes to install)

sudo apt install ubuntu-desktop -y

That is a better representation of what a user who is developing xeus-cpp on Ubuntu will have access to anyway (there is a probably a mimumal ubuntu desktop package but too busy at the moment to look). Most developers won't use a Ubuntu server like OS which has no GUI.

@Alex-PLACET

Copy link
Copy Markdown
Author

@mcbarton the real problem is that ubuntu needs a real or a virtual display (ubuntu-desktop or not).
We could use a github action like this one to keep the diff minimal: https://github.com/marketplace/actions/setup-headless-display-action

@mcbarton

Copy link
Copy Markdown
Collaborator

@mcbarton the real problem is that ubuntu needs a real or a virtual display (ubuntu-desktop or not). We could use a github action like this one to keep the diff minimal: https://github.com/marketplace/actions/setup-headless-display-action

Give the action a go, and see if it gives you a display.

@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@mcbarton

mcbarton commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

@mcbarton the real problem is that ubuntu needs a real or a virtual display (ubuntu-desktop or not). We could use a github action like this one to keep the diff minimal: https://github.com/marketplace/actions/setup-headless-display-action

Give the action a go, and see if it gives you a display.

That appears to work in allowing the tests in run (from a quick glance). I'd just have it skips the tests now (rather than fail) if it doesn't detect the support for webgl in the browser.

@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@mcbarton mcbarton left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR is almost ready. You need to make these changes and update the documentation about the new browser arguments (README.md, CONTRIBUTING.md and InstallationAndUsage.rst).

Comment thread test/test_webgl.cpp Resolved
Comment thread .github/workflows/main.yml Resolved
Comment thread docs/source/dev-build-options.rst Resolved
@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@mcbarton mcbarton left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The browser arguments were not updated in the documentation. Also it still says that the browser tests are headless in the documentation, which they are not anymore.

Comment thread test/CMakeLists.txt Resolved

@mcbarton mcbarton left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After these suggested changes I think I am happy. I would just like a second opinion on whether xeus_cpp_wasm_append_runtime_method is needed

Comment thread docs/source/InstallationAndUsage.rst Resolved
Comment thread CONTRIBUTING.md Resolved
Comment thread README.md Resolved
@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@mcbarton

Copy link
Copy Markdown
Collaborator

@Alex-PLACET can you resolve the merge conflict and squash all the commits into one?

@Alex-PLACET
Alex-PLACET force-pushed the feature/emscripten-webgl-offscreen branch from 28c7862 to 1f28a73 Compare November 13, 2026 16:46

@mcbarton mcbarton left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. I'll now pass this to @anutosh491 in case he has any comments. I don't know if he still wants an example notebook added to xeus-cpps deployment, and i'd like his opinion on whether the xeus_cpp_wasm_append_runtime_method function is needed.

The read the docs failure looks unrelated from a quick glance at the output.

@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

@anutosh491
anutosh491 force-pushed the feature/emscripten-webgl-offscreen branch from 1f28a73 to a9cefc5 Compare November 15, 2026 02:48
Enable the Emscripten WebGL2/OffscreenCanvas link options and export Module.GL for xcpp, add browser WebGL tests, run browser tests non-headless with a Linux display, and document the required Chrome flags.
@mcbarton
mcbarton force-pushed the feature/emscripten-webgl-offscreen branch from a9cefc5 to bac15fa Compare November 15, 2026 08:34
@github-actions

Copy link
Copy Markdown
Contributor

clang-tidy review says "All clean, LGTM! 👍"

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants