@voxel-3d/docs
    Preparing search index...

    Class GLTFLoaderWrapper

    GLTFLoaderWrapper - GLTF/GLB 파일 로더

    Three.js GLTFLoader를 래핑하여 통일된 interface를 제공합니다.

    • GLTF 2.0 지원
    • GLB (바이너리) 지원
    • DRACO 압축 지원 (선택적)
    • 외부 리소스 (.bin, 텍스처) 경로 설정 지원
    • 파일 그룹 로딩 지원 (GLTF + BIN + 텍스처)
    • three-mesh-bvh 자동 적용 (레이캐스팅 가속)
    const loader = new GLTFLoaderWrapper({
      dracoDecoderPath: '/draco/',
      enableBVH: true,
      onProgress: (info) => console.log(`${info.percentage}%`)
    });

    // URL로 로드
    const result = await loader.load('/models/model.glb');
    scene.add(result.scene);

    // 파일 그룹으로 로드 (File API 사용 시)
    const result = await loader.loadWithFiles(gltfFile, fileList);

    Hierarchy (View Summary)

    Index

    Accessors

    state supportedFormats loader loadingManager enableBVH isParallelSupported fileOverlap binCacheInject workerParse workerParseVerify workerLoadPoC materialDedupStats

    Constructors

    constructor

    Methods

    canLoad resetBench getBench getProfile setPath setResourcePath load loadWithFiles loadWithFilesOptimized loadFromBuffer setExternalFileUrlMap clearExternalFileUrlMap cacheFileContent setFileContentCache clearFileContentCache setResourceHandles clearResourceHandles setModelCache loadParallel enableParallelLoading disableParallelLoading setRenderer setDracoLoader setBVHOptions resetMaterialDedup dispose

    Accessors

    • get state(): LoaderState

      로더 state

      Returns LoaderState

    • get supportedFormats(): SupportedFormat[]

      지원 포맷

      Returns SupportedFormat[]

    • get loader(): GLTFLoader

      내부 GLTFLoader 접근

      Returns GLTFLoader

    • get loadingManager(): LoadingManager

      LoadingManager 접근

      Returns LoadingManager

    • get enableBVH(): boolean

      BVH 활성화 여부

      Returns boolean

    • set enableBVH(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get isParallelSupported(): boolean

      Worker Pool 병렬 로딩 지원 여부

      Returns boolean

    • get fileOverlap(): boolean

      Whether the overlapped File API import path is enabled. File API 오버랩 임포트 경로 활성화 여부입니다.

      Returns boolean

      Runtime toggle for loadWithFilesOptimized. When false, File imports use the legacy loadWithFiles path with identical behavior. loadWithFilesOptimized의 런타임 토글. false이면 File 임포트는 기존 loadWithFiles 경로를 동일하게 사용합니다.

    • set fileOverlap(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get binCacheInject(): boolean

      Whether THREE.Cache injection for BIN buffers is enabled. BIN 버퍼에 대한 THREE.Cache 주입 활성화 여부입니다.

      Returns boolean

      Runtime toggle for the loadOptimized BIN handling. When true, BIN ArrayBuffers are injected into THREE.Cache and resolved without object URLs or re-fetch. When false, the legacy Blob URL round-trip is used. loadOptimized의 BIN 처리 런타임 토글. true이면 BIN ArrayBuffer를 THREE.Cache에 주입하여 object URL/재fetch 없이 해석하고, false이면 기존 Blob URL 왕복 경로를 사용합니다.

    • set binCacheInject(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get workerParse(): boolean

      Whether worker-based GLTF/GLB parsing is enabled. Worker 기반 GLTF/GLB 파싱 활성화 여부입니다.

      Returns boolean

      When enabled, the loadOptimized path offloads parsing to a Worker pool. For GLB it parses the buffer directly; for external-resource GLTF it packs an in-memory GLB (GLBPacker) first. Inputs that the lightweight worker parser cannot handle (compression/skin/morph/sparse) silently fall back to the main thread with byte-identical results. When false, parsing always runs on the main thread. 활성화 시 loadOptimized 경로는 파싱을 Worker 풀로 오프로딩합니다. GLB는 버퍼를 직접 파싱하고, 외부 리소스 GLTF는 먼저 in-memory GLB(GLBPacker)로 팩합니다. 경량 worker 파서가 처리할 수 없는 입력(압축/스킨/morph/sparse)은 바이트 단위로 동일한 결과로 조용히 메인스레드로 폴백합니다. false이면 파싱은 항상 메인스레드에서 실행됩니다.

    • set workerParse(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get workerParseVerify(): boolean

      Whether the worker/main-thread 1:1 parse comparison mode is enabled. worker/메인스레드 1:1 파싱 비교 모드 활성화 여부입니다.

      Returns boolean

      Debug-only (design §4.3). When enabled and the worker path is taken, the same packed GLB is also parsed on the main thread and the two results (mesh count, vertex count, material count, animation count) are compared, logging a mismatch. The main-thread result is preserved as the source of truth. Default off; intended for fidelity verification, not production. 디버그 전용(설계 §4.3). 활성화 후 worker 경로를 타면 동일한 팩 GLB를 메인스레드에서도 파싱하여 두 결과(메시 수/정점 수/머티리얼 수/애니메이션 수)를 비교하고 불일치를 로깅합니다. 메인스레드 결과를 진실의 원천으로 유지합니다. 기본 off이며, 충실도 검증용입니다.

    • set workerParseVerify(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get workerLoadPoC(): boolean

      Whether the worker-loading PoC decode path is enabled. 워커 로딩 PoC 디코드 경로 활성화 여부입니다.

      Returns boolean

      Stage-2 PoC gate (workerLoadPoC, design §7). When enabled, up to a small cap of representative external-resource GLTF files are decoded on a robust LoadWorkerPool and assembled on the main thread; the rest and any unsupported/failed input fall back to main-thread parseAsync losslessly. When false, behavior is completely unchanged. Not for production. 2단계 PoC 게이트(workerLoadPoC, 설계 §7). 활성화 시 소수 대표 외부 리소스 GLTF 파일을 견고 LoadWorkerPool에서 디코드하고 메인스레드에서 조립합니다. 나머지와 미지원/실패 입력은 메인스레드 parseAsync로 무손실 폴백합니다. false이면 동작이 완전히 불변입니다. 운영 비권장.

    • set workerLoadPoC(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get materialDedupStats(): MaterialDedupStats

      Returns the current material dedup statistics. 현재 머티리얼 중복 제거 통계를 반환합니다.

      Returns MaterialDedupStats

      Stats with before (distinct instances) and after (unique canonicals); dedup이 비활성이면 { before: 0, after: 0 }. before(서로 다른 인스턴스 수)와 after(고유 대표 수)를 담은 통계.

    Constructors

    Methods

    • URL이 지원되는 포맷인지 확인

      Parameters

      • urlOrFilename: string

        URL 또는 파일명

      Returns boolean

    • Resets the accumulated loadOptimized phase timings. 누적된 loadOptimized phase 타이밍을 초기화합니다.

      Returns void

      import 병목 분석용 계측 헬퍼입니다. 측정 구간 시작 전에 호출합니다. Benchmark helper for import bottleneck analysis. Call before a measured run.

    • Returns the accumulated loadOptimized phase timings and call count. 누적된 loadOptimized phase 타이밍과 호출 수를 반환합니다.

      Returns { phases: Record<string, number>; count: number }

      Object with summed per-phase milliseconds and count of calls. phase별 누적 밀리초 합과 호출 수(count)를 담은 객체.

    • Returns the accumulated synchronous-CPU vs I/O-wait profile of loadOptimized. loadOptimized의 누적 동기 CPU 대 I/O 대기 프로파일을 반환합니다.

      Returns {
          spans: Record<string, number>;
          count: number;
          workerDecodeCount: number;
          mainDecodeCount: number;
          workerDecodeMs: number;
          fallbackReasons: Record<string, number>;
      }

      Object with summed per-span milliseconds (spans) and count of calls 구간별 누적 밀리초(spans)와 호출 수(count)를 담은 객체

      워커 로딩 파이프라인 1단계(설계 §7)의 핵심 계측입니다. phase 합(동시성 대기로 부풀려진 값)이 아니라, 메인스레드에서 소비된 구간을 성격별로 분리합니다: jsonParse/binArrayBuffer/cacheInject/gltfStringify/gltfParse/geomWrap는 동기 CPU(워커 이관 후보), binReadIO는 fetch 등 async I/O 대기(워커 무관)입니다. gltfParse는 GLTFLoader.parse의 동기 accessor 디코드와 텍스처 등 async가 섞인 wall이며, 완전 분리가 불가하므로 동기 근사(upper bound) 로 간주합니다(정직성 주석). 이 모델은 Textures=0이라 async 비중이 작다고 가정합니다. 정확한 동기 self-time은 Chrome Performance User Timing 마커 대조로 확인하십시오. Core step-1 instrumentation (design §7). Splits main-thread spans by nature instead of the concurrency-inflated phase sums. binReadIO is async I/O wait (worker-irrelevant); all other keys are synchronous CPU (worker-offload candidates). gltfParse mixes synchronous accessor decode with async (textures) and is treated as a synchronous upper-bound approximation.

    • 기본 로드 경로 설정

      Parameters

      • path: string

        기본 경로

      Returns this

      GLTF 파일의 기본 경로를 설정합니다. 예: setPath('/models/') 설정 후 load('model.gltf') 호출 시 실제로는 '/models/model.gltf'를 로드합니다.

    • 리소스 경로 설정

      Parameters

      • path: string

        리소스 경로

      Returns this

      GLTF가 참조하는 외부 리소스(.bin, 텍스처)의 기본 경로를 설정합니다. 설정하지 않으면 GLTF 파일의 경로를 기준으로 상대 경로를 해석합니다.

    • GLTF/GLB 파일 load

      Parameters

      • url: string

        파일 URL (일반 URL 또는 Blob URL)

      • Optionalfilename: string

        원본 파일명 (Blob URL인 경우 포맷 감지용)

      Returns Promise<GLTFLoadResult>

    • 파일 그룹으로 GLTF 로드

      Parameters

      • mainFile: ImporterFile

        GLTF/GLB 메인 파일

      • fileList: ImporterFileList

        관련 파일 목록 (bin, 텍스처 포함)

      Returns Promise<GLTFLoadResult>

      GLTF 로드 결과

      File API로 선택한 파일들을 로드할 때 사용합니다. GLTF 파일이 참조하는 .bin 파일과 텍스처를 자동으로 매핑합니다.

      const fileList = new ImporterFileList();
      fileList.fillFromFiles(selectedFiles);

      const gltfFile = fileList.findFileByName('model.gltf');
      const result = await loader.loadWithFiles(gltfFile, fileList);

    • Loads a GLTF/GLB file group through the overlapped optimized path. 오버랩 최적화 경로로 GLTF/GLB 파일 그룹을 로드합니다.

      Parameters

      • mainFile: ImporterFile

        GLTF/GLB main file GLTF/GLB 메인 파일

      • fileList: ImporterFileList

        Related file list (bin, textures) 관련 파일 목록 (bin, 텍스처 포함)

      Returns Promise<GLTFLoadResult>

      GLTF load result GLTF 로드 결과

      단계 ① 구현 (worker 미사용). 동작 흐름:

      1. 관련 BIN/텍스처 File을 ArrayBuffer로 "동시에" 읽기 시작 (await 안 함)
      2. 동시에 메인 GLTF/GLB File을 ArrayBuffer로 읽기
      3. BIN/텍스처 읽기 완료를 await — 메인 읽기/JSON 처리와 오버랩됨
      4. _fileContentCache/_externalFileUrlMap을 채운 뒤 메인스레드 loadOptimized로 위임

      어떤 단계에서든 실패하면 기존 loadWithFiles 경로로 폴백하여 동일한 결과를 보장합니다. 외부 BIN을 메인스레드에서 직접 읽으므로 worker fetch의 blob URL 제약을 우회하며, 오버랩으로 직렬 대기를 줄입니다.

      Error when both the optimized and legacy fallback paths fail 최적화 경로와 폴백 경로가 모두 실패한 경우

    • ArrayBuffer에서 직접 GLTF 파싱

      Parameters

      • buffer: ArrayBuffer

        GLTF/GLB ArrayBuffer

      • path: string = ''

        리소스 해석을 위한 기본 경로

      Returns Promise<GLTFLoadResult>

      GLTF 로드 결과

      이미 메모리에 로드된 GLTF 데이터를 파싱할 때 사용합니다.

    • 외부 파일 URL 맵 설정 (BIN, 텍스처 등)

      Parameters

      • urlMap: Map<string, string>

        파일명 → Blob URL 맵

      Returns void

    • 외부 파일 URL 맵 초기화

      Returns void

    • 파일 콘텐츠 캐시에 추가 (Blob URL fetch 우회용)

      Parameters

      • blobUrl: string

        Blob URL

      • content: ArrayBuffer

        파일 콘텐츠 (ArrayBuffer)

      Returns void

    • 파일 콘텐츠 캐시 일괄 추가

      Parameters

      • cache: Map<string, ArrayBuffer>

        Blob URL → ArrayBuffer 맵

      Returns void

    • 파일 콘텐츠 캐시 초기화

      Returns void

    • Sets the external resource file handles for the worker-load PoC v2 path. 워커 로딩 PoC v2 경로용 외부 리소스 파일 핸들을 설정합니다.

      Parameters

      • handles: Map<string, FileSystemFileHandle>

        Lowercased file name to file handle 소문자 파일명 → 파일 핸들

      Returns void

      PoC v2 핵심 배선. 키는 외부 리소스 파일명(소문자), 값은 FileSystemFileHandle 입니다. _tryWorkerLoadPoC가 gltf JSON의 외부 buffer/image uri를 이 맵에서 해석하여 워커로 핸들을 전달하고, 워커가 handle.getFile()→arrayBuffer()로 바이트를 직접 읽습니다(메인에서 bin ArrayBuffer를 읽지 않음 → 복사·OOM 원천 제거). PoC v2 wiring. Keys are lowercased external resource file names; values are FileSystemFileHandles. _tryWorkerLoadPoC resolves the gltf JSON external buffer/image uris against this map and posts the handles to the worker, which reads the bytes itself (the main thread never reads bin ArrayBuffers → the copy/OOM source is removed).

    • 외부 리소스 파일 핸들 맵 초기화

      Returns void

    • Sets the model cache for HTTP URL caching. HTTP URL 캐싱을 위한 모델 캐시를 설정합니다.

      Parameters

      • cache: IModelCache | null

        Model cache instance 모델 캐시 인스턴스

      Returns void

    • Worker Pool 병렬 로딩으로 GLTF 로드

      Parameters

      • url: string

        GLTF/GLB 파일 URL

      • OptionalonProgress: (progress: ParallelLoadProgress) => void

        진행률 콜백

      Returns Promise<GLTFLoadResult>

      GLTF 로드 결과

      GLTF JSON을 먼저 파싱하고, 참조된 BIN 파일들을 Worker Pool로 병렬 로드합니다. GLB 파일은 단일 파일이므로 일반 로드와 동일하게 처리됩니다.

      const loader = new GLTFLoaderWrapper({
        parallel: { enabled: true, workerCount: 4, debug: true }
      });

      const result = await loader.loadParallel(
        '/models/large-model.gltf',
        (progress) => console.log(`${progress.phase}: ${progress.percentage}%`)
      );

    • Worker Pool 활성화 (런타임)

      Parameters

      • OptionalworkerCount: number

        Worker 수 (기본: CPU 코어 수 기반)

      Returns void

    • Worker Pool 비활성화

      Returns void

    • Sets the WebGLRenderer for KTX2 GPU format detection. KTX2 GPU 포맷 감지를 위한 WebGLRenderer를 설정합니다.

      Parameters

      • renderer: WebGLRenderer

        WebGLRenderer instance WebGLRenderer 인스턴스

      Returns void

    • DRACO 로더 config (런타임)

      Parameters

      • decoderPath: string

      Returns void

    • Resets the material dedup cache for a new import session. 새 임포트 세션을 위해 머티리얼 중복 제거 캐시를 초기화합니다.

      Returns void

      세션 간 오염(이전 모델의 대표 머티리얼이 dispose된 뒤 재사용되는 문제)을 방지하기 위해 각 임포트 시작 시 호출해야 합니다.

    • 리소스 cleanup

      Returns void

    Settings

    Member Visibility

    On This Page

    Accessors
    Constructors
    Methods