preload method

Future<void> preload({ bool includeEnvironments = true, })

Resolves the resources that need asynchronous work (external image assets, encoded image payloads, and fmat materials), caching them so the synchronous realize path finds them ready.

Await this before realizing a document that may reference such resources (the async loaders do). A resource that fails to load degrades to a placeholder (textures) or an unlit material (fmat) with a warning, rather than failing the whole scene.

Set includeEnvironments false to skip realizing EnvironmentResources (which build GPU prefilter cubes, the expensive part). The editor uses this to re-realize just a changed material without re-baking environments.

Implementation

Future<void> preload({bool includeEnvironments = true}) async {
  // Textures first: an fmat material's parameter overrides may reference a
  // texture resource, which must be decoded before the override resolves it.
  final textures = <Future<void>>[];
  for (final resource in document.resources.values) {
    if (resource is TextureResource && _needsAsyncTexture(resource)) {
      textures.add(_preloadTexture(resource));
    }
  }
  await Future.wait(textures);

  final materials = <Future<void>>[];
  for (final resource in document.resources.values) {
    if (resource is MaterialResource && resource.type == 'fmat') {
      materials.add(_preloadFmat(resource));
    }
  }
  await Future.wait(materials);

  // Environments are GPU-bound and async (they build prefilter cubes and may
  // load image assets), so realize them here and cache the result for the
  // synchronous component realize path.
  if (!includeEnvironments) return;
  for (final resource in document.resources.values) {
    if (resource is EnvironmentResource) {
      _environments[resource.id] = await realizeEnvironmentSettings(
        environment: resource.environment,
        environmentIntensity: resource.environmentIntensity,
        exposure: resource.exposure,
        toneMapping: resource.toneMapping,
        radianceCubeSize: resource.radianceCubeSize,
        skybox: resource.skybox,
        skyEnvironment: resource.skyEnvironment,
        bundle: bundle,
        environmentLoader: environmentLoader,
        payloadLookup: document.payload,
      );
    }
  }
}