OpenGLContext 3.0.0a1__py3-none-any.whl

OpenGLContext/bin/ui_demo.py

@@ -0,0 +1,228 @@
+#! /usr/bin/env python
+"""Overlay UI demonstration: the settings screen, the console and a skin.
+
+Run it and press the keys it prints:
+
+    oglc-ui                 # the default flat skin
+    oglc-ui --skin          # the same screens, painted with nine-slice artwork
+
+    F10   the settings screen -- every rendering feature the pass reads
+    F9    the console, with the engine's own log going into it
+    F8    a licence notice, to show a wall of text scrolling
+    F7    a yes/no question
+    F5    save a screenshot (into the current directory)
+    Alt+f the developer overlay -- a HUD layer rather than a panel, so it takes
+          no input and these screens draw over it (see docs/hud.html)
+
+The artwork the ``--skin`` mode uses is drawn at start-up rather than shipped,
+so the demo shows what a nine-slice does -- corners that stay square while the
+frame stretches -- without a binary in the repository.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from typing import Any, List, Optional
+
+from OpenGLContext import testingcontext
+from OpenGLContext.contextdefinition import ContextDefinition
+from OpenGLContext.move import modes as movemodes
+from OpenGLContext.scenegraph.appearance import Appearance
+from OpenGLContext.scenegraph.box import Box
+from OpenGLContext.scenegraph.transform import Transform
+from OpenGLContext.scenegraph.light import DirectionalLight
+from OpenGLContext.scenegraph.material import Material
+from OpenGLContext.scenegraph.quadrics import Sphere
+from OpenGLContext.scenegraph.scenegraph import SceneGraph
+from OpenGLContext.scenegraph.shape import Shape
+from OpenGLContext.ui import bindings, console, dialogs, settings
+from OpenGLContext.ui.overlay import OverlayMixin
+
+log = logging.getLogger(__name__)
+BaseContext: Any = testingcontext.getInteractive()
+
+#: A short licence-shaped wall of text, so the notice screen has to scroll.
+NOTICE = '\n\n'.join([
+    'OpenGLContext is distributed under a BSD-style licence.',
+    'Redistribution and use in source and binary forms, with or without '
+    'modification, are permitted provided that the following conditions are '
+    'met: redistributions of source code must retain the above copyright '
+    'notice, this list of conditions and the following disclaimer; '
+    'redistributions in binary form must reproduce the above copyright notice, '
+    'this list of conditions and the following disclaimer in the documentation '
+    'and/or other materials provided with the distribution.',
+    'THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS '
+    'IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, '
+    'THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR '
+    'PURPOSE ARE DISCLAIMED.',
+] + ['Paragraph %d of a notice nobody can style away.' % (index,)
+     for index in range(1, 40)])
+
+
+def build_skin(directory: str) -> Any:
+    """Draw a nine-slice set into ``directory`` and return a Skin using it.
+
+    Generated rather than shipped: what this demonstrates is that one image
+    serves every widget size, and an image drawn here is as good a proof of
+    that as one drawn in an editor -- with nothing binary to keep in step.
+    """
+    from PIL import Image, ImageDraw
+    from OpenGLContext.ui.skin import NineSlice, Skin
+
+    def frame(name: str, fill: Any, edge: Any, size: int = 24,
+              border: int = 8) -> str:
+        image = Image.new('RGBA', (size, size), (0, 0, 0, 0))
+        draw = ImageDraw.Draw(image)
+        draw.rounded_rectangle([0, 0, size - 1, size - 1], radius=border - 1,
+                               fill=fill, outline=edge, width=2)
+        path = os.path.join(directory, '%s.png' % (name,))
+        image.save(path)
+        return path
+
+    def slice(name: str, fill: Any, edge: Any) -> NineSlice:
+        return NineSlice(url=[frame(name, fill, edge)], border=(8, 8, 8, 8))
+
+    return Skin(
+        panelImage=slice('panel', (18, 22, 32, 230), (90, 110, 150, 255)),
+        buttonImage=slice('button', (38, 46, 62, 245), (110, 130, 170, 255)),
+        buttonHoverImage=slice('button_hover', (64, 88, 130, 250),
+                               (150, 190, 250, 255)),
+        buttonDownImage=slice('button_down', (24, 30, 42, 255),
+                              (90, 110, 150, 255)),
+        buttonDisabledImage=slice('button_off', (28, 30, 34, 180),
+                                  (60, 66, 76, 255)),
+        fieldImage=slice('field', (12, 14, 20, 250), (80, 96, 130, 255)),
+        switchOffImage=slice('switch_off', (12, 14, 20, 250), (110, 130, 170, 255)),
+        switchOnImage=slice('switch_on', (60, 120, 80, 250), (140, 220, 160, 255)),
+        trackImage=slice('track', (12, 14, 20, 250), (70, 84, 112, 255)),
+        thumbImage=slice('thumb', (120, 150, 200, 255), (200, 220, 255, 255)),
+        panelPadding=20.0,
+    )
+
+
+def movement_modes() -> List[Any]:
+    """The ways of moving this demo offers, so the settings screen has some."""
+    return [
+        movemodes.WalkMode(name='walk'),
+        movemodes.FlyMode(name='fly'),
+        movemodes.FPSMode(name='fps'),
+    ]
+
+
+class UIDemoContext(OverlayMixin, BaseContext):
+    """A scene with the overlay screens bound to function keys.
+
+    The mix-in comes first so its event routing runs before the navigation
+    mix-in's: while a modal panel is up the movement sampler is not fed at all.
+    """
+
+    skinned: bool = False
+    skinDirectory: str = ''
+    console: Optional[console.ConsolePanel] = None
+    skin: Any = None
+
+    # Supplied by the interactive context this is built on.
+    addEventHandler: Any
+    frameCounter: Any
+    triggerRedraw: Any
+
+    def OnInit(self) -> None:                   # pragma: no cover - needs a window
+        self.skin = build_skin(self.skinDirectory) if self.skinned else None
+        self.sg = SceneGraph(children=[
+            DirectionalLight(direction=(-0.4, -1, -0.6), intensity=1.0),
+            Transform(translation=(-2, 0, 0), children=[Shape(
+                geometry=Sphere(radius=1.0),
+                appearance=Appearance(material=Material(
+                    diffuseColor=(0.7, 0.3, 0.25))))]),
+            Transform(translation=(2, 0, 0), children=[Shape(
+                geometry=Box(size=(1.6, 1.6, 1.6)),
+                appearance=Appearance(material=Material(
+                    diffuseColor=(0.25, 0.45, 0.7))))]),
+        ])
+        # ``keyboard`` key-downs, not ``keypress``: a function key produces no
+        # character, so GLFW raises no keypress for one and a keypress binding
+        # would be accepted and then never fire.
+        for key, handler in (('<F10>', self.openSettings),
+                             ('<F9>', self.openConsole),
+                             ('<F8>', self.openNotice),
+                             ('<F7>', self.askSomething),
+                             ('<F6>', self.openBindings)):
+            self.addEventHandler('keyboard', name=key, state=1,
+                                 function=handler)
+        sys.stdout.write(__doc__.split('Run it and press')[1])
+        sys.stdout.flush()
+
+    # -- the screens ------------------------------------------------------
+    def _skinned(self, panel: Any) -> Any:
+        if self.skin is not None:
+            panel.skin = self.skin
+        return panel
+
+    def openSettings(self, event: Any) -> None:  # pragma: no cover - needs a window
+        panel = settings.settings_panel(self)
+        self.pushOverlay(self._skinned(panel))
+
+    def openBindings(self, event: Any) -> None:  # pragma: no cover - needs a window
+        panel = bindings.open_bindings(self)
+        if panel is not None:
+            self._skinned(panel)
+
+    def openConsole(self, event: Any) -> None:   # pragma: no cover - needs a window
+        registry = console.CommandRegistry()
+        registry.add('shadows', self._shadowsCommand,
+                     'turn shadows on or off: shadows on|off')
+        registry.add('fps', lambda panel: '%.1f' % (
+            self.frameCounter.recentFps(),), 'the recent frame rate')
+        panel = self._skinned(console.console_panel(registry=registry))
+        panel.write('Type "help" for the commands.')
+        # Engine warnings go where a player can read them.
+        logging.getLogger('OpenGLContext').addHandler(
+            console.ConsoleLogHandler(panel))
+        self.console = panel
+        self.pushOverlay(panel)
+
+    def _shadowsCommand(self, panel: Any, state: str = '') -> str:
+        if state:
+            self.contextDefinition.shadows = state.lower() in ('on', '1', 'true')
+            self.triggerRedraw(1)
+        return 'shadows are %s' % (
+            'on' if self.contextDefinition.shadows else 'off',)
+
+    def openNotice(self, event: Any) -> None:    # pragma: no cover - needs a window
+        self.pushOverlay(self._skinned(
+            dialogs.notice('Licence', NOTICE)))
+
+    def askSomething(self, event: Any) -> None:  # pragma: no cover - needs a window
+        self.pushOverlay(self._skinned(dialogs.confirm(
+            'Download the high-resolution texture pack?',
+            detail='About 40MB, cached for next time.',
+            yes='Download', no='Not now',
+            on_answer=lambda yes: log.warning('answered %s', yes))))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument('--skin', action='store_true',
+                        help='paint the screens with generated nine-slice artwork')
+    parser.add_argument('--skin-dir', default='',
+                        help='where to write that artwork (default: a temp dir)')
+    options = parser.parse_args()
+    directory = options.skin_dir
+    if options.skin and not directory:
+        import tempfile
+        directory = tempfile.mkdtemp(prefix='oglc-ui-skin-')
+    UIDemoContext.skinned = bool(options.skin)
+    UIDemoContext.skinDirectory = directory
+    UIDemoContext.ContextMainLoop(definition=ContextDefinition(
+        title='OpenGLContext overlay UI',
+        size=(1024, 720),
+        movementModes=movement_modes(),
+    ))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

OpenGLContext/bin/view.py

@@ -0,0 +1,341 @@
+#! /usr/bin/env python
+"""Walk-around viewer for a 3D scene (``oglc-view``).
+
+Opens a local file **or an http(s) URL**, renders it with the metallic/roughness
+PBR pass, and lets you walk through it with the keyboard/mouse. What format the
+source is in is worked out from the source itself, so one command opens them
+all:
+
+===============================  ==============================================
+``.gltf`` ``.glb``               a glTF 2.0 model
+``.wrl`` ``.wrz`` ``.vrml``      a VRML97 world
+===============================  ==============================================
+
+Every format gets everything the viewer can do. If the file contains no lights, a
+default sun + fill rig is added so the scene is never rendered in the dark;
+shadows are on by default. A scene that brings its own sky keeps it.
+
+A model with no camera of its own is centred and auto-framed. The fit is on the
+*model*: a part the file stranded far outside the rest is still drawn but does
+not push the camera back to take it in, and the viewer prints a line saying how
+many such parts there are and how far out they go. See docs/viewer.html.
+
+Each camera the scene defines becomes a ``Viewpoint`` node, so PageUp/PageDown
+cycle between them through OpenGLContext's standard viewpoint mechanism; cameras
+are referred to by name where they have one. ``--capture`` renders the scene to a
+PNG and exits, after a short settle delay so the analytic-sky IBL has converged.
+
+Usage::
+
+    oglc-view path/to/model.glb
+    oglc-view path/to/world.wrl
+    oglc-view https://example.com/model.glb
+    oglc-view model.glb --camera aerial --capture shot.png --capture-delay 0.5
+    oglc-view model.glb --list-cameras
+    GLTF=path/to/model.gltf oglc-view
+
+A ``.glb`` is self-contained, so URLs work cleanly. A ``.gltf`` URL fetches only
+that file; models that reference external ``.bin``/texture files by relative URI
+will be missing those (download the whole model set locally instead).
+
+Controls (OpenGLContext's default view-platform navigation)::
+
+    Up / Down arrow        walk forward / back
+    Left / Right arrow     turn (yaw) left / right
+    Ctrl + Up/Down          look up / down (pitch)
+    Alt + Up/Down           move up / down (fly)
+    Alt + Left/Right        strafe (slide) left / right
+    -                       level the horizon
+    right-mouse drag        orbit / examine about a point
+    PgUp / PgDn (or p / n)  cycle named cameras (if any)
+    g                       toggle walk (physics) / free-fly
+    k                       pause / resume animation; [ / ] switch animation
+    t                       stop/start the turntable (stopping resets orientation)
+    F2                      save a screenshot (iso-dated PNG in the current directory)
+    Alt + s                 the same thing through the engine's own handler,
+                            named for the program: oglc-view-screen-0001.png,
+                            also in the current directory
+    Alt + f                 the developer overlay: frame rate and time, which
+                            renderer features are on, what the last frame cost
+                            in shapes and draw calls, and where the camera is
+                            (see docs/hud.html)
+
+Free-fly by default; ``--physics`` (or ``g``) walks the scene instead, with
+gravity and collision keeping you on the ground and out of walls. ``g`` again
+returns to free-fly, so a viewpoint inside the geometry is never a trap.
+
+The viewer itself is :mod:`OpenGLContext.viewer`, which an application can embed
+without this command line, and the formats it opens are the adapters registered
+in :mod:`OpenGLContext.viewer.adapters`; see docs/gltf.html.
+"""
+import argparse
+import os
+import sys
+from typing import Any, Optional
+
+os.environ.setdefault('OPENGLCONTEXT_PROFILE', 'core')
+os.environ.setdefault('OPENGLCONTEXT_BACKEND', 'glfw')
+os.environ.setdefault('OPENGLCONTEXT_RENDERER', 'pbr')
+os.environ.setdefault('OPENGLCONTEXT_SHADOWS', '1')
+# The directional-shadow cascade count is left fps-adaptive for interactive use:
+# each extra cascade is a full depth pass over the whole scene (the dominant
+# shadow-pass cost), so the controller sheds cascades when the frame rate sags.
+# It is pinned only for --capture (see apply_render_env), where a reproducible
+# frame matters more than the frame rate.
+# Keep the warm analytic sky, but at reduced strength so the sun's cast shadows
+# read clearly instead of being washed out by full-strength ambient.
+os.environ.setdefault('OPENGLCONTEXT_IBL_INTENSITY', '0.4')
+
+from OpenGLContext.viewer.adapters import (
+    UnknownSourceType, adapter_for, adapter_named, known_sources,
+)
+from OpenGLContext.viewer.sceneviewer import ViewerContext
+from OpenGLContext.viewer.options import ViewerOptions
+from OpenGLContext.viewer.source import resolve_source
+
+
+# -- command line ---------------------------------------------------------
+
+def _parse_size(text: str) -> tuple[int, int]:
+    """Parse a ``WxH`` window size into an (int, int) tuple."""
+    try:
+        w, h = (int(v) for v in text.lower().split('x'))
+        return (w, h)
+    except Exception:
+        raise argparse.ArgumentTypeError("size must be WxH, e.g. 1100x680") from None
+
+
+def _format_names() -> list[str]:
+    """The registered adapter names, for ``--format``'s help."""
+    from OpenGLContext import plugins
+    return sorted(entry.name for entry in plugins.Adapter.all())
+
+
+def _parse_vec3(text: str) -> tuple[float, ...]:
+    """Parse an ``X,Y,Z`` world-space point."""
+    parts = text.split(',')
+    if len(parts) != 3:
+        raise argparse.ArgumentTypeError('expected X,Y,Z, got %r' % text)
+    return tuple(float(v) for v in parts)
+
+
+def build_parser(prog: str = 'oglc-view') -> argparse.ArgumentParser:
+    """The viewer's command line.
+
+    Every option is declared ``default=argparse.SUPPRESS`` so that an option
+    nobody passed leaves the corresponding :class:`ViewerOptions` field alone.
+    The defaults are the dataclass's, stated once, and the help text below
+    names them where a user needs to know.
+    """
+    parser = argparse.ArgumentParser(
+        prog=prog,
+        description='Walk-around viewer for a 3D scene: %s.' % ', '.join(
+            # Suffixes and conventional file names; the content types the same
+            # adapters answer to are not something anyone types.
+            key for key in known_sources() if '/' not in key),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        argument_default=argparse.SUPPRESS,
+        epilog="A local path or an http(s) URL. .glb is self-contained (URLs work "
+               "cleanly); a .gltf that references external .bin/textures should be "
+               "downloaded locally as a set. Falls back to the GLTF env var.",
+    )
+    parser.add_argument('source', nargs='?',
+                        help='scene file path or http(s) URL (or set GLTF=...)')
+    parser.add_argument('--format', metavar='NAME',
+                        help='read the source as this format instead of guessing '
+                             'from its name (%s); for a URL that serves a scene '
+                             'from a path with no suffix'
+                             % ', '.join(_format_names()))
+    parser.add_argument('--camera', metavar='NAME|INDEX',
+                        help='initial camera, by the name the scene gives it '
+                             '(preferred) or 0-based index')
+    parser.add_argument('--list-cameras', action='store_true',
+                        help="print the scene's camera names and exit")
+    parser.add_argument('--no-cameras', action='store_true',
+                        help="ignore the scene's own cameras; centre and auto-frame it")
+    parser.add_argument('--capture', metavar='PATH',
+                        help='render to PATH (PNG) after settling, then exit')
+    parser.add_argument('--capture-delay', type=float, metavar='SECONDS',
+                        help='seconds to let the scene settle before --capture (default 0.5)')
+    parser.add_argument('--frames', type=int, metavar='N',
+                        help='minimum frames to render before --capture (default 10)')
+    parser.add_argument('--shadows', action=argparse.BooleanOptionalAction,
+                        help='force shadows on/off (default: on)')
+    parser.add_argument('--lights', choices=['auto', 'on', 'off'],
+                        help="default light rig: auto (add only if the file has none), "
+                             "on (always add), off (never add)")
+    parser.add_argument('--ibl-intensity', type=float, metavar='SCALE',
+                        help='scale the analytic-sky ambient/IBL contribution')
+    parser.add_argument('--environment', metavar='PREFIX|HDR|NAME',
+                        help='image-based environment: a cubemap face prefix '
+                             '(<PREFIX>{RT,LF,UP,DN,FR,BK}.jpg), an equirectangular '
+                             'Radiance .hdr panorama (local path or http(s) URL), or a '
+                             'bundled CC0 HDRI name (e.g. studio_small_03). Reflected '
+                             'by metals and drawn as the skybox. Pins full IBL.')
+    parser.add_argument('--background', metavar='SPEC',
+                        help="background: 'sky' (default), 'none', or 'R,G,B'")
+    parser.add_argument('--size', type=_parse_size, metavar='WxH',
+                        help='window size, e.g. 1100x680')
+    # Streaming sources (3D Tiles): ignored by a format that is read once.
+    parser.add_argument('--sse', type=float, metavar='PIXELS',
+                        help='streamed datasets: max screen-space error in '
+                             'pixels; lower = more detail (default 16)')
+    parser.add_argument('--memory', type=int, metavar='MiB',
+                        help='streamed datasets: resident tile memory budget '
+                             '(default 512)')
+    parser.add_argument('--no-recenter', dest='no_recenter', action='store_true',
+                        help='streamed datasets: do not shift a geospatial '
+                             '(Earth-centred) dataset to the origin')
+    parser.add_argument('--cache-dir', dest='cache_dir', metavar='DIR',
+                        help='where to cache data fetched from a URL')
+    parser.add_argument('--physics', action=argparse.BooleanOptionalAction,
+                        help='walk the model with gravity + collision (default off, so '
+                             'an isolated/floorless model stays framed instead of the '
+                             'avatar falling past it); press "g" or pass --physics to walk')
+    parser.add_argument('--turntable', action='store_true',
+                        help='slowly rotate the model')
+    parser.add_argument('--no-rotate', dest='no_rotate', action='store_true',
+                        help='never rotate the model (fixed orientation, to line a '
+                             'capture up with a reference image)')
+    parser.add_argument('--animation', metavar='NAME|INDEX',
+                        help='play this glTF animation (name or 0-based index); '
+                             'default: play the first animation if any')
+    parser.add_argument('--no-animation', dest='animate', action='store_false',
+                        help='do not play embedded animations')
+    parser.add_argument('--anim-time', type=float, metavar='SECONDS',
+                        help='pin the animation to this time (deterministic capture)')
+    parser.add_argument('--yaw', type=float,
+                        help='initial model yaw (radians) when auto-framing '
+                             '(default -0.62, or the YAW env var)')
+    parser.add_argument('--margin', type=float, metavar='FACTOR',
+                        help='auto-frame fit factor (default 1.15); below 1 pulls '
+                             'the camera in so the model fills more of the frame')
+    parser.add_argument('--elevation', type=float, metavar='FRAC',
+                        help='auto-frame camera height as a fraction of the model '
+                             'radius (default 0.22)')
+    parser.add_argument('--tilt', type=float, metavar='RADIANS',
+                        help='auto-frame downward camera tilt in radians (default 0.10)')
+    parser.add_argument('--eye', type=_parse_vec3, metavar='X,Y,Z',
+                        help='explicit camera position (world space); with --look-at '
+                             'this bypasses auto-framing (e.g. an interior shot)')
+    parser.add_argument('--look-at', dest='look_at', type=_parse_vec3,
+                        metavar='X,Y,Z', help='explicit camera target (world space)')
+    return parser
+
+
+def parse_args(argv: list[str] | None = None, prog: str = 'oglc-view',
+               options: ViewerOptions | None = None) -> ViewerOptions:
+    """Parse the viewer's command line into a :class:`ViewerOptions` (no GL).
+
+    ``options`` is filled in and returned when given, so a program built on this
+    one can start from its own defaults and let the user override them.
+    """
+    return build_parser(prog).parse_args(
+        argv, namespace=options if options is not None else ViewerOptions())
+
+
+def _is_hdr_environment(spec: str | None) -> bool:
+    """Whether ``--environment SPEC`` names a Radiance ``.hdr`` panorama.
+
+    An equirectangular ``.hdr``/``.pic`` (local path or http(s) URL) is treated as
+    an HDR IBL source + skybox; anything else is a six-face cubemap prefix. The
+    query string of a URL is ignored so a CDN link with parameters still matches.
+    """
+    if not spec:
+        return False
+    path = spec.split('?', 1)[0].split('#', 1)[0]
+    return path.lower().endswith(('.hdr', '.pic'))
+
+
+def apply_render_env(args: ViewerOptions) -> None:
+    """Translate render-affecting options into the variables the renderer reads.
+
+    These are start-up switches read once by the passes (see
+    :mod:`OpenGLContext.renderoptions`), so they are set before a context exists
+    rather than carried on the options object.
+    """
+    if args.shadows is not None:
+        os.environ['OPENGLCONTEXT_SHADOWS'] = '1' if args.shadows else '0'
+    if args.ibl_intensity is not None:
+        os.environ['OPENGLCONTEXT_IBL_INTENSITY'] = str(args.ibl_intensity)
+    if args.environment:
+        from OpenGLContext.loaders import hdri
+        try:
+            args.environment = hdri.resolve(args.environment)   # catalogue name -> URL
+        except KeyError:
+            pass    # not a catalogue name; treat as a cubemap prefix / path
+        environment: str = args.environment
+        if _is_hdr_environment(environment):
+            # An equirectangular Radiance .hdr (local path or URL): drives the IBL
+            # probe and the HDR skybox. The probe loads it via OPENGLCONTEXT_ENV_HDR.
+            os.environ['OPENGLCONTEXT_ENV_HDR'] = environment
+        else:
+            os.environ['OPENGLCONTEXT_ENV_CUBEMAP'] = environment
+        os.environ.setdefault('OPENGLCONTEXT_IBL', 'full')   # env probe needs full IBL
+    elif (args.background == 'none'
+          and not os.environ.get('OPENGLCONTEXT_ENV_CUBEMAP')
+          and not os.environ.get('OPENGLCONTEXT_ENV_HDR')):
+        # A self-lit scene (its own KHR_lights_punctual, black backdrop, NO env probe)
+        # must get no analytic-sky IBL, or the ambient sky washes it pale grey instead
+        # of the dark scene its lights make. But only when there is genuinely no
+        # environment: the browser demo defaults --background 'none' yet loads an env
+        # cubemap probe for metals to reflect, so forcing IBL off there rendered every
+        # metal black. Honour an explicit env cubemap or HDR panorama.
+        os.environ['OPENGLCONTEXT_IBL'] = 'off'
+    if args.capture:
+        # a --capture run wants a clean frame, not the fps overlay
+        os.environ['OPENGLCONTEXT_DISABLE_FPS_DISPLAY'] = '1'
+        # A capture must be reproducible: pin the otherwise fps-adaptive cascade
+        # count so the shadows don't vary with the frame rate between runs. An
+        # explicit user setting still wins.
+        os.environ.setdefault('OPENGLCONTEXT_SHADOW_CASCADES', '3')
+        # Nobody is watching a capture, and a *mapped* surface is what makes it
+        # hang: a compositor throttles the swap to its own frame callback, and
+        # with no window on screen consuming frames the swap never returns. A
+        # hidden window renders and reads back identically. Both stay
+        # overridable, since watching a capture happen is how you find out why
+        # it looks wrong.
+        os.environ.setdefault('OPENGLCONTEXT_HIDDEN', '1')
+        os.environ.setdefault('OPENGLCONTEXT_NO_VSYNC', '1')
+
+
+class TestContext(ViewerContext):
+    """``oglc-view`` itself: the viewing component, configured from the command line."""
+
+
+def _list_cameras(source: str, format: Optional[str] = None) -> int:
+    """Print the scene's camera names, for choosing one with ``--camera``.
+
+    The adapter answers, so this works for every format rather than only the one
+    the listing was first written for.
+    """
+    adapter = adapter_named(format) if format else adapter_for(source)
+    scene = adapter.load(source)
+    if not scene.cameras:
+        sys.stdout.write("(no cameras defined in %s)\n" % os.path.basename(source))
+    for i, camera in enumerate(scene.cameras):
+        sys.stdout.write("%d: %s\n" % (i, camera.get('name') or 'camera'))
+    return 0
+
+
+def main(argv: Optional[list[str]] = None, prog: str = 'oglc-view') -> Any:
+    parser = build_parser(prog)
+    options = parser.parse_args(argv, namespace=ViewerOptions())
+    source = options.source or os.environ.get('GLTF')
+    if options.list_cameras and not source:
+        parser.error('nothing to list cameras for (pass a path or a URL)')
+
+    if options.list_cameras:
+        try:
+            return _list_cameras(resolve_source(source) or source, options.format)
+        except UnknownSourceType as error:
+            parser.error(str(error))
+
+    apply_render_env(options)
+    TestContext.options = options
+    return TestContext.ContextMainLoop(size=options.size) if options.size \
+        else TestContext.ContextMainLoop()
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI entry point
+    main()

OpenGLContext/bin/vrml_view.py

@@ -0,0 +1,42 @@
+#! /usr/bin/env python
+"""``oglc-vrml`` -- the former VRML97-only viewer, now an alias for ``oglc-view``.
+
+There is one viewer, and it works out the format from the source, so the command
+that opens a ``.wrl`` is the command that opens a ``.glb``.  A VRML world opened
+this way gains everything that was previously only in the glTF viewer: framing,
+loading in the background, camera cycling over the world's own ``Viewpoint``
+nodes, a caption, screenshots, ``--capture``, and walking with gravity and
+collision.  See :mod:`OpenGLContext.bin.view`.
+
+The old ``--shaders`` / ``--no-shaders`` switches are gone: they reached into the
+render pass from inside ``Redraw`` to turn on shader rendering, and the viewer
+now renders through the core-profile PBR pass as a matter of course.  A world
+that genuinely wants the compatibility pipeline gets it from the environment,
+which is where every other renderer switch lives::
+
+    OPENGLCONTEXT_PROFILE=compatibility oglc-view world.wrl
+
+This name is kept for one release cycle so existing scripts and documentation
+keep working, and prints where to go instead.  It will then be removed.
+"""
+import sys
+from typing import Any, Optional
+
+from OpenGLContext.bin.view import main as view_main
+
+#: What to type now.  Named here so the notice and the replacement cannot drift.
+REPLACEMENT = 'oglc-view'
+
+
+def main(argv: Optional[list] = None) -> Any:
+    """Run ``oglc-view``, having said that is what this now is."""
+    sys.stderr.write(
+        "oglc-vrml is deprecated and will be removed; use %s instead "
+        "(it opens every format, and a world gets the full viewer).\n"
+        % REPLACEMENT)
+    sys.stderr.flush()
+    return view_main(argv, prog='oglc-vrml')
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI entry point
+    main()