Interface GLTFLoaderOptions

Remarks

When enabled, the loadOptimized path offloads parsing to a Worker pool. GLB buffers are parsed directly; external-resource GLTF is first packed into an in-memory GLB (GLBPacker) so the same worker handles it unmodified. Inputs the lightweight worker parser cannot handle (compression, skin, morph, sparse accessors) silently fall back to the main thread with byte-identical results. Turning it off forces main-thread parsing. 활성화 시 loadOptimized 경로는 파싱을 Worker 풀로 오프로딩합니다. GLB는 직접 파싱하고, 외부 리소스 GLTF는 먼저 in-memory GLB(GLBPacker)로 팩하여 동일 worker가 무수정으로 처리합니다. 경량 worker 파서가 처리할 수 없는 입력(압축/스킨/morph/sparse)은 바이트 단위로 동일한 결과로 조용히 메인스레드로 폴백합니다. off 시 파싱은 메인스레드에서 실행됩니다.

Remarks

Worker-loading gate (workerLoadPoC). When enabled, external-resource GLTF files are decoded on a robust LoadWorkerPool (file handles read inside the worker, zero main-to-worker copy) and assembled on the main thread. Unsupported/failed inputs fall back to main-thread parsing losslessly. Promoted to default ON after measurement (365 files: 8.0s to 1.74s, 4.6x). 워커 로딩 게이트(workerLoadPoC). 활성화 시 외부 리소스 GLTF 파일을 견고 LoadWorkerPool에서 디코드(파일 핸들을 워커가 직접 읽음, 메인→워커 복사 0)하고 메인스레드에서 조립합니다. 미지원/실패 입력은 메인스레드 파싱으로 무손실 폴백합니다. 실측(365파일: 8.0s→1.74s, 4.6배) 후 기본 ON으로 승격.

Remarks

Recorded right after material dedup on both the worker and main load paths, so the captured material references are canonical. Without a sink, missing textures are silently left as empty slots (the pre-existing behavior). GLB inputs never record, as they cannot reference external image files. 워커/메인 두 로드 경로 모두 머티리얼 dedup 직후에 기록하므로 잡은 머티리얼 참조는 대표 인스턴스입니다. 싱크가 없으면 누락 텍스처는 빈 슬롯으로 조용히 남습니다 (기존 동작). GLB는 외부 이미지 파일을 참조할 수 없으므로 기록하지 않습니다.

Remarks

When enabled, File-based imports route through loadWithFilesOptimized, which starts reading external BIN/texture ArrayBuffers concurrently with the main GLTF/GLB read and delegates to the loadOptimized path. Turning it off restores the legacy loadWithFiles behavior exactly. 활성화 시 File 기반 임포트는 외부 BIN/텍스처를 메인 파일 읽기와 동시에 읽어 loadOptimized 경로로 위임하는 loadWithFilesOptimized를 사용합니다. off 시 기존 loadWithFiles 동작과 정확히 동일하게 폴백합니다.

Remarks

When enabled, the loadOptimized path injects already-loaded BIN ArrayBuffers directly into THREE.Cache (keyed by a unique plain key) and points the GLTF buffer.uri at that key, so GLTFLoader resolves the buffer from cache without creating an object URL or re-fetching. The injected keys are removed in a finally block to avoid leaking into the global cache. Turning it off restores the legacy Blob URL round-trip for BIN buffers with identical results (zero regression). 활성화 시 loadOptimized 경로는 이미 로드된 BIN ArrayBuffer를 고유한 평문 키로 THREE.Cache에 직접 주입하고 GLTF buffer.uri를 그 키로 지정하여, GLTFLoader가 object URL 생성/재fetch 없이 캐시에서 버퍼를 해석하도록 합니다. 주입한 키는 finally에서 제거하여 전역 캐시 누수를 방지합니다. off 시 BIN 버퍼는 기존 Blob URL 왕복 경로로 동일하게 동작합니다(회귀 0).

Remarks

동일 속성 머티리얼을 하나의 대표 인스턴스로 통합하여 머티리얼별 draw call 그룹화와 GPU 메모리 사용을 개선합니다. 교체된 중복 원본은 dispose됩니다.

공유 안전성:

• HighlightManager color 모드(기본)는 머티리얼을 교체(swap)하므로 안전합니다. emissive/opacity/wireframe 모드는 clone-on-write로 격리됩니다.
• ClippingManager section(both) 투명화는 머티리얼 단위 백업(dedup 인지)이므로 안전합니다.
• MaterialManager 편집 경로는 per-mesh clone-on-write(ensureCurrentMaterial)로 안전합니다.
• MissingTextureManager 재적용은 대표 머티리얼을 직접 변조하지만 이는 의도된 동작입니다. gltf가 그 슬롯을 그 머티리얼들에 선언했으므로 대표에 적용하는 것이 정답입니다. dedup 키는 pending 텍스처 판별자를 포함하므로, 서로 다른 uri를 기다리는 머티리얼은 병합되지 않습니다(오적용 방지). 같은 uri를 기다리는 머티리얼끼리는 계속 병합됩니다.
• 제약: TextureManager 편집 경로는 clone-on-write가 없어 공유 머티리얼을 직접 변조합니다. dedup 활성 시 한 메시에 텍스처를 적용하면 동일 대표 머티리얼을 공유하는 다른 메시에도 반영될 수 있습니다. 완전 격리가 필요하면 이 옵션을 false로 두거나 TextureManager에 clone-on-write를 추가하십시오.