filly 0.1.0__tar.gz → 0.2.0__tar.gz

{filly-0.1.0 → filly-0.2.0}/NOTES.md

@@ -1,6 +1,6 @@
 Misc things
  - ~~psychopy frequently operates in floats, even for window sizes. Accept floats
-   for SharedTarget and coerce to ints?~~ Done: target sizes accept integral floats;
+   for HostTarget and coerce to ints?~~ Done: target sizes accept integral floats;
    fractional or non-finite values raise ValueError.
  - KHR_xmp_json_ld?
  - Feels like wheel was reinvented unnecessarily, e.g. some of the custom shaders?

{filly-0.1.0 → filly-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: filly
-Version: 0.1.0
+Version: 0.2.0
 Summary: A Python 3D renderer for glTF scenes, built on Google Filament
 Author: Alex Forrence
 License-Expression: MIT
@@ -9,19 +9,19 @@ Project-URL: Homepage, https://github.com/aforren1/filly
 Project-URL: Documentation, https://github.com/aforren1/filly#readme
 Project-URL: Issues, https://github.com/aforren1/filly/issues
 Requires-Python: >=3.10
-Requires-Dist: numpy>=1.24
+Requires-Dist: numpy>=1.22
 Provides-Extra: examples
-Requires-Dist: Pillow>=10; extra == "examples"
+Requires-Dist: Pillow>=9.1; extra == "examples"
 Provides-Extra: psychopy
-Requires-Dist: psychopy-lib==2026.2.4; extra == "psychopy"
+Requires-Dist: psychopy>=2024.2; extra == "psychopy"
 Provides-Extra: pyglet
 Requires-Dist: pyglet>=1.4.11; extra == "pyglet"
 Provides-Extra: moderngl
 Requires-Dist: pyglet>=1.4.11; extra == "moderngl"
-Requires-Dist: moderngl>=5.12; extra == "moderngl"
+Requires-Dist: moderngl>=5.7; extra == "moderngl"
 Provides-Extra: zengl
 Requires-Dist: pyglet>=1.4.11; extra == "zengl"
-Requires-Dist: zengl>=2.7; extra == "zengl"
+Requires-Dist: zengl>=2.1; extra == "zengl"
 Description-Content-Type: text/markdown
 
 # filly
@@ -41,10 +41,9 @@ such as PsychoPy experiments or pyglet, moderngl, and zengl programs.
 
 ## Install
 
-filly is not on PyPI yet. [Build it from source](docs/how-to/build.md).
+You can install filly from [PyPI](https://pypi.org/project/filly/) or [build it from source](docs/how-to/build.md).
 
-It needs Python 3.10 or later, Windows or Linux on x86_64, and an OpenGL 4.1 driver. On Linux,
-offscreen rendering works without a display. macOS is not supported at this time.
+It needs Python 3.10 or later, Windows or Linux on x86_64, and an OpenGL 4.1 driver. On Linux, offscreen rendering works without a display. macOS is not supported at this time.
 
 ## Render an image
 
@@ -57,10 +56,8 @@ with filly.Renderer() as renderer:
     horse = scene.load("examples/assets/wooden_playground_horse.glb")
     horse.apply_animation(0, 1.25) # a pose from its spring animation
 
-    camera = scene.create_camera()
-    camera.set_perspective(fov_y=30, near=0.1, far=100)
-    camera.frame(horse, direction=(-1, -0.3, -1), aspect=800 / 600)
-    scene.camera = camera
+    scene.camera = renderer.create_camera()
+    scene.camera.frame(horse, direction=(-1, -0.3, -1))
     scene.add_directional_light(direction=(-1, -1, -2), intensity=100_000)
 
     target = renderer.create_render_target(width=800, height=600)
@@ -74,20 +71,18 @@ filly renders into a texture that PsychoPy draws directly, with no copy through
 
 ```python
 from psychopy import core, visual
-from filly.integrations.psychopy import SharedTarget, create_renderer
+from filly.integrations.psychopy import HostTarget, create_renderer
 
 win = visual.Window((1024, 768), units="pix")
 renderer = create_renderer(win) # shares the window's OpenGL context
 scene = renderer.create_scene()
 horse = scene.load("examples/assets/wooden_playground_horse.glb")
-camera = scene.create_camera()
-camera.set_perspective(fov_y=30, near=0.1, far=100)
-camera.frame(horse, aspect=1)
-scene.camera = camera
+scene.camera = renderer.create_camera()
+scene.camera.frame(horse)
 scene.add_directional_light(direction=(-1, -1, -2), intensity=100_000)
 
-target = SharedTarget(renderer, win, 512, 512)
-stim = target.as_psychopy_texture() # an ImageStim
+target = HostTarget(renderer, win, width=512, height=512)
+stim = target.create_image_stim()
 clock = core.Clock()
 while clock.getTime() < 3:
     horse.apply_animation(0, clock.getTime())
@@ -95,12 +90,11 @@ while clock.getTime() < 3:
     stim.draw()
     win.flip()
 
-target.close()
 renderer.close()
 win.close()
 ```
 
-Close the target, then the renderer, then the window. The same pattern works with a
+Close the renderer before the window. The same pattern works with a
 [pyglet, moderngl, or zengl window](docs/how-to/gl-hosts.md).
 
 ## Features
@@ -116,6 +110,8 @@ Close the target, then the renderer, then the window. The same pattern works wit
 - **Predictable output:** sRGB (default) or linear. Effects such as antialiasing,
   fog, and bloom are off until you enable them. With default settings, the same scene gives the same pixels on every frame.
 - **Several views per frame:** each `render()` call can take its own camera and viewport, for example for side-by-side stereo.
+- **Picking:** find the model, node, and world position under a pixel of a rendered frame, for
+  example where a participant clicked. See [picking](docs/reference/api.md#picking).
 - **Browsers:** the same core compiles to WebAssembly for WebGL2. It renders into a texture that the page's own renderer draws, such as PIXI in PsychoJS. See
   [the web build](docs/explanation/web.md).
 
@@ -126,11 +122,13 @@ See the `examples/` folder.
 | Example | Shows |
 | --- | --- |
 | `screenshot.py` | The animation above (`--gif`), or a still image, rendered offscreen. |
-| `psychopy_shared.py` | A model in a PsychoPy window. Pass your own GLB path. |
-| `pyglet_shared.py`, `moderngl_shared.py`, `zengl_shared.py` | The same in other OpenGL hosts. |
+| `psychopy_shared.py` | A model in a PsychoPy window with all the bells and whistles. Pass your own GLB path. |
+| `psychopy_stress.py` | Repeated PsychoPy trials, with frame timing and memory reports. See [measure timing](docs/how-to/stress-test.md). |
+| `pyglet_shared.py`, `moderngl_shared.py`, `zengl_shared.py` | The same (minus the bells and whistles) in other OpenGL hosts. |
 | `drifting_grating.py` | A texture updated every frame on a tilted plane. |
 | `stereo.py` | Two cameras side by side in one window. |
 | `shapes.py` | Generated and deforming meshes. |
+| `pick.py` | Click a model in a pyglet window: picking, with the hit node, point, and latency. `--auto` clicks by itself. |
 
 ## Documentation
 
@@ -141,8 +139,10 @@ See the `examples/` folder.
   [compare with Filament's viewer](docs/how-to/reference-comparison.md),
   [use filly in a web page](docs/how-to/web.md)
 - Reference: [API](docs/reference/api.md), [performance](docs/reference/performance.md),
-  [validation](docs/reference/validation.md), [sample assets](docs/reference/sample-assets.md)
+  [validation](docs/reference/validation.md), [sample assets](docs/reference/sample-assets.md),
+  [upstream Filament issues](docs/reference/upstream-issues.md)
 - Explanation: [design and limits](docs/explanation/design.md),
+  [filly and Filament](docs/explanation/filament.md),
   [tested assumptions](docs/explanation/assumptions.md),
   [material precompilation](docs/explanation/material-precompilation.md),
   [the web build](docs/explanation/web.md)

{filly-0.1.0 → filly-0.2.0}/README.md

@@ -15,10 +15,9 @@ such as PsychoPy experiments or pyglet, moderngl, and zengl programs.
 
 ## Install
 
-filly is not on PyPI yet. [Build it from source](docs/how-to/build.md).
+You can install filly from [PyPI](https://pypi.org/project/filly/) or [build it from source](docs/how-to/build.md).
 
-It needs Python 3.10 or later, Windows or Linux on x86_64, and an OpenGL 4.1 driver. On Linux,
-offscreen rendering works without a display. macOS is not supported at this time.
+It needs Python 3.10 or later, Windows or Linux on x86_64, and an OpenGL 4.1 driver. On Linux, offscreen rendering works without a display. macOS is not supported at this time.
 
 ## Render an image
 
@@ -31,10 +30,8 @@ with filly.Renderer() as renderer:
     horse = scene.load("examples/assets/wooden_playground_horse.glb")
     horse.apply_animation(0, 1.25) # a pose from its spring animation
 
-    camera = scene.create_camera()
-    camera.set_perspective(fov_y=30, near=0.1, far=100)
-    camera.frame(horse, direction=(-1, -0.3, -1), aspect=800 / 600)
-    scene.camera = camera
+    scene.camera = renderer.create_camera()
+    scene.camera.frame(horse, direction=(-1, -0.3, -1))
     scene.add_directional_light(direction=(-1, -1, -2), intensity=100_000)
 
     target = renderer.create_render_target(width=800, height=600)
@@ -48,20 +45,18 @@ filly renders into a texture that PsychoPy draws directly, with no copy through
 
 ```python
 from psychopy import core, visual
-from filly.integrations.psychopy import SharedTarget, create_renderer
+from filly.integrations.psychopy import HostTarget, create_renderer
 
 win = visual.Window((1024, 768), units="pix")
 renderer = create_renderer(win) # shares the window's OpenGL context
 scene = renderer.create_scene()
 horse = scene.load("examples/assets/wooden_playground_horse.glb")
-camera = scene.create_camera()
-camera.set_perspective(fov_y=30, near=0.1, far=100)
-camera.frame(horse, aspect=1)
-scene.camera = camera
+scene.camera = renderer.create_camera()
+scene.camera.frame(horse)
 scene.add_directional_light(direction=(-1, -1, -2), intensity=100_000)
 
-target = SharedTarget(renderer, win, 512, 512)
-stim = target.as_psychopy_texture() # an ImageStim
+target = HostTarget(renderer, win, width=512, height=512)
+stim = target.create_image_stim()
 clock = core.Clock()
 while clock.getTime() < 3:
     horse.apply_animation(0, clock.getTime())
@@ -69,12 +64,11 @@ while clock.getTime() < 3:
     stim.draw()
     win.flip()
 
-target.close()
 renderer.close()
 win.close()
 ```
 
-Close the target, then the renderer, then the window. The same pattern works with a
+Close the renderer before the window. The same pattern works with a
 [pyglet, moderngl, or zengl window](docs/how-to/gl-hosts.md).
 
 ## Features
@@ -90,6 +84,8 @@ Close the target, then the renderer, then the window. The same pattern works wit
 - **Predictable output:** sRGB (default) or linear. Effects such as antialiasing,
   fog, and bloom are off until you enable them. With default settings, the same scene gives the same pixels on every frame.
 - **Several views per frame:** each `render()` call can take its own camera and viewport, for example for side-by-side stereo.
+- **Picking:** find the model, node, and world position under a pixel of a rendered frame, for
+  example where a participant clicked. See [picking](docs/reference/api.md#picking).
 - **Browsers:** the same core compiles to WebAssembly for WebGL2. It renders into a texture that the page's own renderer draws, such as PIXI in PsychoJS. See
   [the web build](docs/explanation/web.md).
 
@@ -100,11 +96,13 @@ See the `examples/` folder.
 | Example | Shows |
 | --- | --- |
 | `screenshot.py` | The animation above (`--gif`), or a still image, rendered offscreen. |
-| `psychopy_shared.py` | A model in a PsychoPy window. Pass your own GLB path. |
-| `pyglet_shared.py`, `moderngl_shared.py`, `zengl_shared.py` | The same in other OpenGL hosts. |
+| `psychopy_shared.py` | A model in a PsychoPy window with all the bells and whistles. Pass your own GLB path. |
+| `psychopy_stress.py` | Repeated PsychoPy trials, with frame timing and memory reports. See [measure timing](docs/how-to/stress-test.md). |
+| `pyglet_shared.py`, `moderngl_shared.py`, `zengl_shared.py` | The same (minus the bells and whistles) in other OpenGL hosts. |
 | `drifting_grating.py` | A texture updated every frame on a tilted plane. |
 | `stereo.py` | Two cameras side by side in one window. |
 | `shapes.py` | Generated and deforming meshes. |
+| `pick.py` | Click a model in a pyglet window: picking, with the hit node, point, and latency. `--auto` clicks by itself. |
 
 ## Documentation
 
@@ -115,8 +113,10 @@ See the `examples/` folder.
   [compare with Filament's viewer](docs/how-to/reference-comparison.md),
   [use filly in a web page](docs/how-to/web.md)
 - Reference: [API](docs/reference/api.md), [performance](docs/reference/performance.md),
-  [validation](docs/reference/validation.md), [sample assets](docs/reference/sample-assets.md)
+  [validation](docs/reference/validation.md), [sample assets](docs/reference/sample-assets.md),
+  [upstream Filament issues](docs/reference/upstream-issues.md)
 - Explanation: [design and limits](docs/explanation/design.md),
+  [filly and Filament](docs/explanation/filament.md),
   [tested assumptions](docs/explanation/assumptions.md),
   [material precompilation](docs/explanation/material-precompilation.md),
   [the web build](docs/explanation/web.md)

{filly-0.1.0 → filly-0.2.0}/docs/explanation/assumptions.md

@@ -264,11 +264,11 @@ path and sets it in gltfio's parse, which cgltf then skips. No GLB is assembled.
   | Sponza | 0.88 s | 51 to 55 ms | 0.49 to 0.63 s | 243 to 269 ms |
   | NodePerformanceTest | 3.6 to 3.8 s | 1.4 to 1.8 s | 2.6 to 2.7 s | 2.3 to 2.6 s |
 
-- `Renderer.finish()` waits by request. `OffscreenTarget.read()` must wait for the readback.
+- `Renderer.finish()` waits by request. `RenderTarget.read()` must wait for the readback.
 - `ImportedTarget.close()` must wait for imported textures, because the host can then delete or
   reuse the texture name. For owned targets the wait is conservative.
-- `set_environment()` waits after the prefilter work. Filament orders the destroy commands itself,
-  so the wait is conservative. It keeps setup cost out of later frames.
+- `Renderer.load_environment()` and `create_environment()` wait after the prefilter work.
+  Filament orders the destroy commands itself, so the wait is conservative. It keeps setup cost out of later frames.
 
 **Verdict.** The load wait is not needed for memory safety. It is useful for experiments.
 

{filly-0.1.0 → filly-0.2.0}/docs/explanation/design.md

@@ -5,10 +5,14 @@ Nanobind converts Python values at the boundary. Filament types stay in the nati
 The Windows WGL and Linux GLX adapters are isolated in `native/gl_interop.cpp`, and the Linux
 headless EGL platform in `native/egl_platform.cpp`.
 
+For how filly's concepts map to Filament and gltfio, and which code depends on Filament
+internals, see [filly and Filament](filament.md).
+
 ## Ownership
 
 Every native resource retains the engine state. The engine tracks resources through weak references.
-This prevents ownership cycles. A scene retains its models, cameras, and added lights.
+This prevents ownership cycles. A scene retains its models, its added lights, and its current
+camera. Cameras belong to the renderer.
 Objects can keep the engine alive after the Python `Renderer` reference is deleted.
 
 `renderer.close()` waits for outstanding work and destroys resources before the engine.
@@ -18,31 +22,46 @@ Model and light `close()` release scene ownership and queue native destruction.
 handles invalidate their nodes, node-local materials, and imported lights. A removed imported light
 keeps its transform entity so animation can continue. Added lights use a separate owner whose
 closed state prevents old handles from referring to a replacement light. `Scene.close()` releases
-the scene's children, detaches its cameras from other scenes, and then destroys its view,
-Filament scene, color grading, and environment.
-
-A loaded glTF asset is a shared native object. The first model and each `clone()` are gltfio
-instances of it: `AssetLoader::createInstance()` adds entities, material instances, lights,
-skins, and an animator, and reuses vertex buffers, textures, and materials. gltfio 1.77.1 has no
-way to destroy one instance, so closing a model only removes its entities from the scene; the
-asset and all its instances are destroyed when the last model closes. `createInstance()` needs
-the asset's source data, about the file size in CPU memory, and each instance needs the
-preparation tables for the custom materials, property animation, cameras, and morph weights. Cloning is
-therefore opt-in: `scene.load(..., clonable=True)` keeps them, and the default calls
-`releaseSourceData()` and drops the tables after the first instance. For DamagedHelmet
-(3.6 MiB file) this saves 3.7 MiB of private bytes per loaded asset. The process grows by
-113 MiB per loaded DamagedHelmet on the tested Intel GPU, most of it texture memory that the
-integrated GPU allocates in system memory, so the saving is small for textured assets. Name
-lookups use each instance's own node table, because gltfio's name and entity lists cover all
-instances.
-
-The asset belongs to the renderer; each model holds it. A clone can therefore go into another
-scene of the same renderer, and closing a scene closes only its own models. Textures that the
-material provider decodes for filly's custom materials are kept by source in the asset's tables,
-so clones share them as they share gltfio's textures. Before, each clone decoded them again and
-kept the copies until the asset closed.
-
-`Model.memory` estimates what the asset holds. gltfio lists no textures or buffers, so the
+the scene's children (a closing model detaches its imported cameras from every scene), and then
+destroys its view, Filament scene, color grading, and the scene's environment light and skybox. Renderer cameras, assets, and
+environments stay open for other scenes.
+
+A loaded glTF asset is a shared native object that the renderer owns, as Filament's engine owns
+its textures and buffers. Each model is a gltfio instance of it:
+`AssetLoader::createInstance()` adds entities, material instances, lights, skins, and an
+animator, and reuses vertex buffers, textures, and materials. gltfio 1.77.1 has no way to destroy
+one instance, so closing a model only removes its entities from the scene; the asset and all
+its instances are destroyed when the asset handle and the last model close.
+`createInstance()` needs the asset's source data, about the file size in CPU memory, and each
+instance needs the preparation tables for the custom materials, property animation, cameras, and
+morph weights. An open `Asset` keeps them; `Asset.close()` calls `releaseSourceData()` and drops
+the tables. `scene.load()` is a load, one `add()`, and that release, so a model that nothing
+adds again costs no source data. For DamagedHelmet (3.6 MiB file) the release saves 3.7 MiB of
+private bytes. The process grows by 113 MiB per loaded DamagedHelmet on the tested Intel GPU,
+most of it texture memory that the integrated GPU allocates in system memory, so the saving is
+small for textured assets. Name lookups use each instance's own node table, because gltfio's
+name and entity lists cover all instances.
+
+An asset handle replaced `scene.load(source, clonable=True)` and `model.clone(scene=...)`. With
+those, an asset could only be created through a scene: keeping a prototype needed a hidden model
+in some scene, and closing that scene closed the prototype. A clone also copied nothing that a
+new instance lacks: it started from the asset's authored state, as an added model does. The
+asset belongs to the renderer and each model holds it, so any scene of the renderer can add it,
+and closing a scene closes only its own models. Textures that the material provider decodes for
+filly's custom materials are kept by source in the asset's tables, so models share them as they
+share gltfio's textures. Before, each instance decoded them again and kept the copies until the
+asset closed.
+
+Loading creates the first instance before `ResourceLoader::loadResources()`, and the first
+`add()` uses it. gltfio uploads morph target data only in `loadResources()`, which runs once per
+asset, and only for the instances that exist then; an asset loaded without instances gave every
+model empty morph targets. Later instances get their
+morph target positions from the source data and their morph tangent frames from gltfio's own
+`TangentsJob`, under the same conditions as `loadResources()`, so every model of an asset
+morphs the same. A test compares the lit, morphed first and second models pixel by pixel.
+Before, clones had empty morph targets.
+
+`Asset.memory` and `Model.memory` estimate what the asset holds. gltfio lists no textures or buffers, so the
 estimate collects them itself: a texture provider wrapper records the textures that gltfio's
 providers create, and each is sized from its internal format, dimensions, and mip levels. Vertex,
 index, morph target, and bone buffers are sized at preparation from the glTF accessors with the
@@ -88,8 +107,13 @@ the warning, and Filament has no other switch. A 60 Hz loop, or a 1 ms sleep per
 log it. In embedded mode, the host owns the window and every
 display-buffer swap. See [tested assumptions](assumptions.md).
 
-Shadows, refraction, FXAA, MSAA, SSAO, bloom, dithering, fog, depth of field, and vignette are
-scene properties and disabled by default. The PsychoPy demo enables refraction and FXAA.
+Shadows, FXAA, MSAA, SSAO, bloom, dithering, fog, depth of field, and vignette are
+scene properties and disabled by default. The PsychoPy demo enables FXAA. Screen-space
+refraction is not an option. Every scene has it on: transmission and volume materials render as
+flat white without it, and Filament runs the pass only in frames that draw such a material.
+Until October 2026 it was a scene property. That property looked like a render option, but no
+material depended on it; only a load-time warning did, which gave the rule "set it before
+loading glass".
 Temporal antialiasing, TAA upscaling, screen-space reflections, and dynamic resolution are not
 exposed. In Filament 1.77.1 `PostProcessManager`, TAA and screen-space reflections import the
 previous frame's history buffer (`FrameHistory::getPrevious()`), and dynamic resolution scales
@@ -149,7 +173,7 @@ the UV sets of the glTF textures. Nothing is compiled.
 A generated mesh is loaded as a one-triangle glTF with the requested material and attributes,
 then its renderable gets the mesh's own vertex and index buffers (`setGeometryAt()`). The loader
 therefore gives it the same material as a glTF file with those factors, and the model gets
-nodes, material handles, clones, and closing without a second code path. The placeholder's
+nodes, material handles, and closing without a second code path. The placeholder's
 accessor bounds are the mesh bounds. Positions, tangent frames, UVs, and colors are separate
 vertex buffers, so an update uploads only what changed. A mesh without colors gets a white
 `UBYTE4` color buffer, and `UV1` reads the `UV0` buffer: archive entries serve every material,
@@ -159,12 +183,13 @@ its method that writes into the staging buffer; a test checks that both give the
 Missing normals are area-weighted vertex normals, because shared vertices of an indexed mesh
 should be smooth; flat faces need their own vertices.
 
-A host texture input uses the same fences as a shared render target, in the other direction.
+An imported texture (`ImportedTexture`) uses the same fences as a shared render target, in the
+other direction.
 Leaving `write()` places a host fence, and the next render of a scene whose models sample the
 texture queues a Filament-side wait on it before the frame. After such a render, Filament places
-one fence, which the texture shares with the target and with the other sampled host textures,
+one fence, which the texture shares with the target and with the other sampled imported textures,
 and entering `write()` queues a host-side wait on it. Each Filament fence costs a `glFlush()` on
-Filament's thread, so a render places at most one. A scene that does not sample a host texture
+Filament's thread, so a render places at most one. A scene that does not sample an imported texture
 neither waits for its writes nor fences it. Neither side waits on the CPU.
 
 Two kinds of per-frame work run only when something changed. A camera whose projection follows
@@ -182,10 +207,33 @@ from the bind frame moves it away from the geometry. Preparation computes the bo
 asset: accessor boxes through node transforms for rigid meshes, and every vertex skinned with the
 rest pose for skinned meshes. A 1,000,000-vertex skinned mesh loaded in 120 ms against 65 ms
 for the same mesh without a skin; the difference also includes gltfio's own skin work and the
-joint and weight uploads (Iris Xe laptop, September 30, 2026). Clones share the box, and
+joint and weight uploads (Iris Xe laptop, September 30, 2026). Models of an asset share the box, and
 frames do no bounds work. The same rest-pose box, in the mesh node's frame, replaces gltfio's
 culling box for skinned renderables, which had the same fault and could cull a visible mesh.
 
+gltfio also has `FilamentInstance::recomputeBoundingBoxes()`. It skins every vertex with the
+joints' current transforms and sets the culling boxes of one instance. filly does not use it.
+A prototype that called it once per asset and copied the boxes to later models gave these results
+(October 12, 2026, Iris Xe laptop):
+
+- It ignores morph targets on skinned primitives. The box of a skinned mesh does not include its
+  morph targets.
+- It reads `JOINTS_0` and `WEIGHTS_0` without checks. A skinned primitive without these
+  attributes stopped the process with an access violation; filly loads it. A joint index past
+  the end of the skin's joint list reads outside an array.
+- One large primitive is slower: 149 ms against 54 ms for a skinned primitive with 1,000,000
+  vertices. gltfio runs one job per primitive, so the same vertices in 8 primitives took 34 ms
+  against 58 ms.
+- It reads every position of rigid meshes: 6 ms for 1,000,000 vertices, against less than
+  0.1 ms for accessor bounds. In the Khronos sample assets, the accessor bounds gave the same
+  boxes as the data.
+- It joins the primitive boxes of a mesh in the node's frame. filly moves each primitive box into
+  the model's frame first, which gives a smaller box under a rotated node.
+
+On the 149 Khronos sample assets that load (of 150) and the horse demo, `Model.bounds` and
+`Node.bounds` from the two methods agreed within 0.01% of the box size, except in three assets
+with rotated multi-primitive meshes. There, filly's boxes were smaller, by up to 0.14% of the model and 10% of one node.
+
 ## Output encoding
 
 The encoding does not depend on other options. Earlier, disabling postprocessing wrote linear
@@ -211,7 +259,7 @@ value is encoded:
 | --- | --- | --- |
 | None (default) | The scene view, rendering straight into the RGBA16F buffer | No |
 | MSAA | Filament's multisampled RGB16F buffer, resolved and copied into the RGBA16F buffer | No |
-| Refraction, SSAO, shadows, fog | Their passes; the color pass as without them | No |
+| Refraction materials (transmission, volume), SSAO, shadows, fog | Their passes; the color pass as without them | No |
 | Transparent view | Filament's RGBA16F color buffer, blended into the RGBA16F buffer | No |
 | FXAA | Nothing: filly's FXAA pass runs after the encode pass, on the encoded image | No |
 | Dithering | Nothing: the encode pass adds the noise after the transfer function | No |
@@ -376,7 +424,8 @@ setting has no effect there.
 
 ## Shared OpenGL textures
 
-The default Filament WGL platform does not implement external sync creation. The wrapper supplies
+Filament's desktop platforms (WGL, GLX, and EGL) do not implement external sync creation; only
+Android's EGL platform does. See [upstream issues](../reference/upstream-issues.md). The wrapper supplies
 a small WGL, GLX, or EGL platform subclass through Filament's public platform interface, for
 offscreen engines too. It places GL fences, waits, and the `GL_FRAMEBUFFER_SRGB` setting in the Filament
 command stream through `Engine::createSync()`.
@@ -394,7 +443,23 @@ waited for it; its release replaces the unconsumed host fence.
 This orders both producer and consumer GPU work. Normal frames do not use `glFinish()` or CPU
 framebuffer copies. Explicit shutdown and image readback can block for completion.
 
-The PsychoPy adapter uses `ImageStim`'s texture-provider interface and owns the host texture.
+The adapters own OpenGL objects that the renderer does not know: the host texture, a draw
+program, and PsychoPy stimuli. An imported target therefore takes an optional callback, which
+`Renderer.close()` calls before it releases anything else, while the host context can still be
+made current. Each adapter passes a callback that closes its target. The callback holds the
+target weakly: the renderer holds the callback, and a strong reference would form a cycle
+through native objects that Python's garbage collector cannot see. The callbacks run in
+`Renderer.close()` only, not when the renderer's state is destroyed: each target holds that
+state, so no target exists then. Thus the renderer's close leaves no host objects behind, and
+only the window must close last.
+
+`draw()` blends premultiplied source-over by default in every adapter, because that is what
+Filament writes. The pyglet and moderngl adapters draw a quad in native code that saves and
+restores the OpenGL state that it changes. moderngl cannot read its blend state back, and
+libraries that cache OpenGL state need it restored. A blit, which the pyglet adapter used
+before, cannot blend.
+
+The PsychoPy adapter draws with `ImageStim` and owns the host texture.
 Its draw method runs inside `acquire()`. PsychoPy remains responsible for
 `win.flip()`. PsychoPy skips a context switch when it believes its window is current, which is
 wrong after other code switched contexts through pyglet, so the adapter also checks pyglet's
@@ -420,8 +485,12 @@ adapter converts sampled RGB to straight RGB in a shader, before ImageStim appli
 The temporary shader selection is restored after each draw so regular PsychoPy stimuli keep their
 normal rendering behavior. The host window uses average blending.
 
-The adapter is pinned to psychopy-lib 2026.2.4 because it uses PsychoPy's context and texture
-internals. Other versions and backends need separate tests.
+The adapter uses PsychoPy's context and texture internals, so each PsychoPy version needs its
+own test. It does not use texture providers (an `image` with `colorTexture`), which
+`ImageStim` takes in PsychoPy 2026.2 but not in 2024.2. It gives `ImageStim` a placeholder
+image and then replaces the texture name. The legacy GL path records the program and the
+texture in a display list, so the adapter rebuilds the list in its first draw, with the
+premultiplied program in place. Other backends need separate tests.
 
 ## Dependencies
 
@@ -479,7 +548,7 @@ A load has these steps:
 7. `AssetLoader::createInstance()` with index markers (below), then `ResourceLoader`.
 
 The loaded buffer memory lives with the asset until gltfio releases its source data, which is
-after the first instance unless `clonable=True`.
+until the `Asset` closes; `scene.load()` releases it after its one model.
 
 gltfio identifies nothing by glTF index. Its `MaterialProvider` callbacks get a key, a UV map, a
 label (the material name), and the extras text, and its entity lists are not in node order. While
@@ -536,16 +605,20 @@ the pinned SDK implements this path despite older wording in its LightManager he
 map size and bias settings use the same options for authored and imported lights. Shadows remain
 explicit opt-in at both scene and light levels.
 
-The scene retains the source environment cubemap and a Skybox object alongside the filtered IBL
-textures. Visibility attaches or detaches the skybox without changing lighting. IndirectLight's
+An `Environment` holds the source environment cubemap and the filtered IBL textures, and the
+renderer owns it. Each scene that uses it builds its own IndirectLight and Skybox from those
+textures, because the IndirectLight holds the intensity and rotation, which are scene settings.
+Building them took 0.03 to 0.3 ms per scene, where filtering the panorama again took 54 to 83 ms.
+Visibility attaches or detaches the skybox without changing lighting. IndirectLight's
 rotation controls both the skybox and native IBL; custom diffuse backlighting receives the same
-rotation update. Clearing or replacing the environment detaches the skybox before destroying its
-texture. A visible skybox writes opaque background pixels even in a transparent view.
-
-Python normalizes modern meshopt buffers and expands instance attributes before animation
-decoding and native loading. A namespaced meshoptimizer 1.0 decoder avoids symbol collisions
-with the SDK's older decoder. Instance children share mesh resources, but this path does not
-reduce draw calls with explicit GPU batching. Node visibility is evaluated in parent-first order
+rotation update. Removing or replacing a scene's environment destroys only that scene's light and
+skybox; closing the environment removes it from every scene first, then destroys its
+textures. A visible skybox writes opaque background pixels even in a transparent view.
+
+Native [glTF preparation](#gltf-preparation) decodes meshopt buffers and expands
+`EXT_mesh_gpu_instancing` before gltfio loads the document. Instance children share mesh resources and
+material instances, so Filament's automatic instancing, which every renderer turns on, draws up
+to 64 of them per call (8 in WebGL). Node visibility is evaluated in parent-first order
 without per-frame allocation and controls scene membership for meshes and lights.
 
 Volume materials use filly's solid refraction entries. Filament 1.77.1 passes only a mesh
@@ -583,14 +656,15 @@ cubemap is used as is, and the spherical harmonics in its metadata supply diffus
 comes from the roughest reflection level. Filament's KTX parser and upload abort on malformed
 input, so the wrapper checks the file structure first. The custom diffuse-transmission material
 needs an irradiance cubemap; it is filtered from a full-mip copy of the IBL's sharpest level.
-The filter runs only when a model with that material is in the scene, at the environment load or
-at the model load, whichever comes later: it cost about 60 ms per environment, plus about 35 ms
+The filter runs only when a model with that material is in a scene that uses the environment,
+when the scene gets the environment or the model, whichever comes later, and once per
+environment: it cost about 60 ms, plus about 35 ms
 to build the filter once per renderer (256-pixel IBL, desktop). It performs GPU work and a
 completion wait during setup. Each prefilter object builds its material on first use. Shader
 compilation in the driver on first use, image decoding, and environment filtering belong outside
 a trial's frame loop.
 The renderer creates Filament's IBL prefilter objects once and reuses them. When they were
-destroyed after each call, models loaded after `set_environment()` could render black on
+destroyed after each call, models loaded after an environment could render black on
 Intel and NVIDIA. The cause inside Filament is not isolated.
 
 glTF animation restores authored transforms and morph weights before evaluating a clip, which
@@ -616,7 +690,8 @@ the scan over a model's copies allocates nothing.
 Camera projection and UV transform tracks update grouped values, then rebuild each matrix once
 after channel evaluation. This prevents channel order from producing invalid intermediate clip
 planes or overwriting another UV channel. Imported camera handles borrow glTF-owned components.
-Closing an asset detaches its active cameras from every scene before destroying those components.
+`Asset.close()` releases only the source data. Closing a model closes its imported cameras and
+detaches them from every scene; the components stay until the asset goes.
 
 The build follows [nanobind's packaging interface](https://nanobind.readthedocs.io/en/latest/packaging.html)
 with CMake and scikit-build-core. Windows links the pinned release SDK. Linux builds the same
@@ -658,7 +733,7 @@ UBO fence reclamation while the driver waits for more commands. A wait without a
 (`FENCE_WAIT_FOR_EVER`, a `time_point::max()` deadline) uses an untimed wait. The converted
 deadline overflows, so `wait_until()` returns at once; Filament's frame-info thread then spins on
 the fence mutex and starves the driver thread that would signal the fence. The first
-`OffscreenTarget.read()` after a render hung this way. The corrections preserve asynchronous
+`RenderTarget.read()` after a render hung this way. The corrections preserve asynchronous
 rendering and do not add GPU completion waits.
 
 Shared GLX contexts use the host's X display connection. Opening a separate connection can