createCubeTextureFromPixels method

@override TextureHandle createCubeTextureFromPixels({ required int size, required TextureFormat format, required List<ByteData> faces, List<List<ByteData>>? mipLevels, })

Uploads six square images as one cube texture.

faces are in the order every graphics API in use agrees on: +X, −X, +Y, −Y, +Z, −Z. Documented once, here, because it is the piece of this that has no natural check: a table with two entries transposed produces a sky that is complete, seamless and wrong, and it looks like a sky somebody authored badly rather than like a bug. The conformance check a cube map answers the face a direction points at draws six known directions against six known colours for exactly this, through the cube-sky stage pair, and names the transposed pair when it fails.

Every face is size by size — cube faces are square by definition, and a rectangular one is a mistake worth refusing rather than resizing.

Throws UnsupportedCapabilityException when the device cannot make cubes, and a DeviceResourceException when there are not six faces or a face is not the size its description says — the same rule as createTextureFromPixels, whose caller decides whether an asset that disagrees about its own dimensions costs a texture or the frame.

mipLevels are the smaller copies, from half size downwards: one entry per level, each holding six faces in the same order as faces. Null or empty gives a cube with a base level only, which is what a sky wants.

Roughness is what these are for. A sky is sampled at one level and needs none; a prefiltered radiance map is a cube whose levels are the roughness scale, each one the environment convolved a little further. That is the one use, and it is why this takes a chain the caller has already built rather than offering to generate one: the levels are not a box blur of each other, and a device that filled them by halving would produce something that looks nearly right and is wrong everywhere it matters.

Built above the seam for the same reason createTextureFromPixels's are — flutter_gpu has no generateMipmap — so both backends receive the same bytes and the two golden sets stay comparable.

Ask features.has(DeviceFeature.cubeTextures) first.

Implementation

@override
TextureHandle createCubeTextureFromPixels({
  required int size,
  required TextureFormat format,
  required List<ByteData> faces,
  List<List<ByteData>>? mipLevels,
}) =>
    _guard(
      'a ${size}x$size ${format.name} cube',
      () => webgpuCreateCubeTextureFromPixels(
        _gpuDevice,
        _textures,
        size: size,
        format: format,
        faces: faces,
        mipLevels: mipLevels,
      ),
    ) ??
    (throw refuseResource(
      'createCubeTextureFromPixels',
      'six ${size}x$size ${format.name} faces (and a chain of six a '
          'level, each half the last) were not what was given, or this '
          'device has no spelling for the format',
    ));