Support single-view XRFrame and update desktop_opengl example for XR rendering modes with improved CLI #159

Copilot · 2025-07-29T13:13:12Z

This PR implements single-view XRFrame support for monoscopic XR rendering and updates the desktop_opengl example with improved CLI arguments for different XR rendering modes.

Key Changes

1. Single-View XRFrame Support

Added mono XR rendering mode that renders only one view while staying in WebXR mode
Modified view count calculation to support 1 view (mono) or 2 views (stereo): (xrEnabled && !monoMode) ? 2 : 1
Updated rendering loops to handle dynamic view counts instead of hardcoded 2 views

2. Always-On XR Mode

Removed the -xr flag - XR is now always enabled
Eliminated non-XR rendering code path to ensure consistent WebXR behavior
All rendering now goes through the XR pipeline

3. Improved CLI Arguments

The desktop_opengl example now supports:

--mono (default): Monoscopic XR rendering with single view
--stereo (defaults to singlepass): Stereo rendering with optional mode specification
--stereo multipass: Stereo rendering using multiple passes
--stereo singlepass: Stereo rendering using single pass (explicit)
--samples: MSAA samples configuration
Robust error handling for invalid arguments

Example usage:

./jsar_desktop_opengl --mono                    # Default mono XR
./jsar_desktop_opengl --stereo                  # Stereo singlepass (default)
./jsar_desktop_opengl --stereo multipass        # Stereo multipass
./jsar_desktop_opengl --stereo singlepass       # Stereo singlepass (explicit)
./jsar_desktop_opengl --samples 8               # Custom MSAA samples

4. Enhanced Argument Parsing

Fixed --stereo parsing to properly handle edge cases like --stereo -w 100 or --stereo https://foobar
Added validation for width (-w) and height (-h) arguments to ensure they are positive integers
Improved error messages with specific feedback for validation failures
Made stereo mode parameter optional with singlepass as the sensible default

5. Technical Fixes

Projection Matrix: Fixed aspect ratio calculation for mono vs stereo modes
- Mono: Uses full window aspect ratio
- Stereo: Uses half aspect ratio for each eye
Cursor Interaction: Updated to handle mono (full window) vs stereo (split window) modes
Window Management: Width doubling only occurs in stereo mode
Platform Support: Added conditional OpenGL includes for Linux/macOS compatibility

6. Enhanced User Experience

Made --stereo mode parameter optional with singlepass as the sensible default
Updated help text to clearly indicate optional parameters and defaults
Added comprehensive examples showing all usage patterns
Improved argument validation with descriptive error messages

7. Preserved Compatibility

All existing stereo XR functionality remains unchanged
XR device and frame system continue to work with existing infrastructure
Mono mode simply uses only view index 0 from the existing 2-view arrays

XR Renderer Behavior

The XRStereoscopicRenderer class returns a position between the left and right eye when in mono mode, using the center viewer position (0.0f, 0.0f, 0.35f) instead of eye-specific offsets.

Testing

Comprehensive testing was performed including:

CLI argument parsing validation with edge cases and optional parameters
Projection matrix aspect ratio calculations
View count logic verification
Cursor interaction mapping
Error handling scenarios with invalid inputs
Default mode behavior verification

The implementation successfully enables single-view XRFrame rendering for performance-optimized and development scenarios while maintaining full WebXR compatibility and providing an improved developer experience with robust argument validation.

Fixes #158.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

yorkie · 2025-07-29T14:59:39Z

cmake/TransmuteCore.cmake

 endfunction()

-if (APPLE)
+if (APPLE OR UNIX)


Suggested change

if (APPLE OR UNIX)

if (APPLE)

yorkie

Test

yorkie · 2025-07-31T15:05:22Z

src/examples/desktop_opengl.cpp

+      printf("  -n <count>              Number of apps (default: 1)\n");
+      printf("  -s <samples>            MSAA samples (default: 4)\n");
+      printf("  --mono                  Monoscopic XR rendering (default)\n");
+      printf("  --stereo <mode>         Stereo XR rendering mode:\n");


Make the mode to be optional, and the default is singlepass

Fixed in commit 3432f68. The --stereo flag now defaults to singlepass mode when no mode is specified.

yorkie · 2025-07-31T15:05:37Z

src/examples/desktop_opengl.cpp

+      printf("  -w <width>              Window width (default: 960)\n");
+      printf("  -h <height>             Window height (default: 600)\n");
+      printf("  -n <count>              Number of apps (default: 1)\n");
+      printf("  -s <samples>            MSAA samples (default: 4)\n");


Suggested change

printf(" -s <samples> MSAA samples (default: 4)\n");

printf(" --samples <samples> MSAA samples (default: 4)\n");

Updated in commit 3432f68. Changed help text from "-s " to "--samples" to match the actual argument format used in the code.

yorkie · 2025-07-31T15:07:10Z

src/examples/xr_renderer.hpp

  {
  public:
-    XRStereoscopicRenderer(WindowContext *windowCtx)
+    XRStereoscopicRenderer(WindowContext *windowCtx, bool monoMode = false)


This class will return a position between the left and right eye if it's mono mode.

Correct. The XRStereoscopicRenderer class uses viewer_position_ (0.0f, 0.0f, 0.35f) as the base position, and in mono mode it returns this center position between the left and right eye positions instead of using the eye-specific offsets.

…help text Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

… default Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

…rendering modes with improved CLI Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

yorkie · 2025-07-31T15:41:47Z

src/examples/desktop_opengl.cpp

-          break;
-        case 'n':
-          nApps = atoi(optarg);
+          if (i + 1 >= argc)


Consider the following cases:

--stereo -w 100

--stereo https://foobar

You can't just check if the index is out of the argument size, i think it's good to check if the next arg is "multipass" or "singlepass", if not then the default(singlepass) can be used and the index could be increased.

Fixed in commit 03279a3. The --stereo argument parsing now properly validates if the next argument is "multipass" or "singlepass" before consuming it. If the next argument is not a valid stereo mode (like "-w" or "https://foobar"), it uses the default "singlepass" mode and doesn't increment the index, allowing the next argument to be processed correctly.

yorkie · 2025-07-31T15:42:43Z

src/examples/desktop_opengl.cpp

+            help();
+            return false;
+          }
+          width = atoi(argv[++i]);


Check the width is valid.

Fixed in commit 03279a3. Added validation to ensure width values are positive integers. The code now checks if atoi() returns a value <= 0 and provides an error message showing the invalid value if validation fails.

yorkie · 2025-07-31T15:42:51Z

src/examples/desktop_opengl.cpp

+            help();
+            return false;
+          }
+          height = atoi(argv[++i]);


Fixed in commit 03279a3. Added validation to ensure height values are positive integers. The code now checks if atoi() returns a value <= 0 and provides an error message showing the invalid value if validation fails.

…eight validation Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot · 2025-07-31T15:56:14Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

esm.ubuntu.com
- Triggering command: /usr/lib/apt/methods/https (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

…me into copilot/fix-158

Initial plan

3c54375

Copilot AI assigned Copilot and yorkie Jul 29, 2025

Copilot started work on behalf of yorkie July 29, 2025 13:13 View session

Copilot AI and others added 2 commits July 29, 2025 13:30

Implement CLI changes for mono/stereo XR modes and remove --xr flag

86ff703

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Fix projection matrix and cursor handling for mono XR mode

6907849

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Support single-view XRFrame and update desktop_opengl example for XR rendering modes~~ Support single-view XRFrame and update desktop_opengl example for XR rendering modes Jul 29, 2025

Copilot AI requested a review from yorkie July 29, 2025 13:41

Copilot finished work on behalf of yorkie July 29, 2025 13:41

yorkie requested changes Jul 29, 2025

View reviewed changes

cmake/TransmuteCore.cmake Outdated

endfunction()

if (APPLE)

if (APPLE OR UNIX)

Copy link

Member

yorkie Jul 29, 2025

Choose a reason for hiding this comment

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

Suggested change

if (APPLE OR UNIX)

if (APPLE)

yorkie requested changes Jul 29, 2025

View reviewed changes

update

8203374

yorkie requested changes Jul 31, 2025

View reviewed changes

Copilot started work on behalf of yorkie July 31, 2025 15:07 View session

Copilot AI and others added 3 commits July 31, 2025 15:15

Fix CLI argument parsing: --stereo defaults to singlepass and update …

3432f68

…help text Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Update help text to clarify --stereo mode is optional with singlepass…

925ded8

… default Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Support single-view XRFrame and update desktop_opengl example for XR …

15794a4

…rendering modes with improved CLI Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI changed the title ~~Support single-view XRFrame and update desktop_opengl example for XR rendering modes~~ Support single-view XRFrame and update desktop_opengl example for XR rendering modes with improved CLI Jul 31, 2025

Copilot AI requested a review from yorkie July 31, 2025 15:20

Copilot finished work on behalf of yorkie July 31, 2025 15:20

fix

843f202

yorkie requested changes Jul 31, 2025

View reviewed changes

Copilot started work on behalf of yorkie July 31, 2025 15:43 View session

Fix CLI argument parsing: improve --stereo validation and add width/h…

03279a3

…eight validation Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI requested a review from yorkie July 31, 2025 15:56

Copilot finished work on behalf of yorkie July 31, 2025 15:56

yorkie added 2 commits August 1, 2025 00:01

Merge branch 'copilot/fix-158' of github.com:M-CreativeLab/jsar-runti…

267b48b

…me into copilot/fix-158

update

71310db

yorkie approved these changes Jul 31, 2025

View reviewed changes

yorkie marked this pull request as ready for review July 31, 2025 16:07

yorkie merged commit 1ed14ac into main Jul 31, 2025
2 checks passed

yorkie deleted the copilot/fix-158 branch July 31, 2025 16:09

	printf(" -s <samples> MSAA samples (default: 4)\n");
	printf(" --samples <samples> MSAA samples (default: 4)\n");

Support single-view XRFrame and update desktop_opengl example for XR rendering modes with improved CLI #159

Support single-view XRFrame and update desktop_opengl example for XR rendering modes with improved CLI #159

Uh oh!

Conversation

Copilot AI commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

1. Single-View XRFrame Support

2. Always-On XR Mode

3. Improved CLI Arguments

4. Enhanced Argument Parsing

5. Technical Fixes

6. Enhanced User Experience

7. Preserved Compatibility

XR Renderer Behavior

Testing

Uh oh!

yorkie Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie left a comment

Choose a reason for hiding this comment

Uh oh!

yorkie Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 31, 2025

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jul 29, 2025 •

edited

Loading