Texture

Картинка на 3D-поверхности: GPU-текстура, которую сэмплит Material (map, юниформы); декодируется нативно 3D-движком. Картинка 2D-спрайта — это Texture2D: эти два типа не взаимозаменяемы; если проект использует файл в обоих мирах, загрузи его в оба.

  • наложить картинку на 3D-объект
  • загрузить карту нормалей или маску без преобразования цвета
  • сжатые текстуры KTX2, чтобы экономить память на мобильных
  • текстура из сгенерированных пикселей
  • показать нарисованный канвас на 3D-поверхности
  • чтобы текстура не повторялась на краях
  • качество текстур: анизотропная фильтрация и лимит размера
  • видео на 3D-экране

Платформы: iOS, Android, десктоп, веб, веб-плеер, приложение-вьюер le.codes. Android (и его вьюер) и веб хранят PNG/JPG как цвет, что бы ни говорил srgb — у KTX2 решает его собственный заголовок; в вебе нет Texture.fromCanvas, и он игнорирует anisotropy / maxSize; headless-тесты ничего не декодируют и не проигрывают видео.

Обзор

TypeScript
const main = async () => {
  const scene = new Scene()
  scene.add(Light.sun())
  scene.open()

  const tex = await Texture.load(asset('./crate.jpg'))
  const crate = Mesh.box({ material: Material.lit({ map: tex }) })
  scene.add(crate)
}
main()

Загрузка картинки как текстуры: Texture.load

TypeScript
Texture.load(source: string | FetchResponse | File, options?: {
  srgb?: boolean       // по умолчанию true: ЦВЕТ, хранится в sRGB; false = ДАННЫЕ (карта нормалей, маска, карта высот), остаются линейными
  fullSize?: boolean   // игнорировать Texture.maxSize для этой текстуры (таблица поиска); по умолчанию false
}): Promise<Texture>

Принимает URL-строку (ассет/удалённый), уже скачанный FetchResponse или File (например, из openFilePicker). Загрузки по URL отклоняются при HTTP-ошибках (статус ≥ 400); любая загрузка отклоняется при ошибке декодирования. PNG / JPG декодирует платформа, с цепочкой мипов на хостах, которые её строят.

Карты нормалей, маски и карты высот: srgb: false

Карту нормалей, маску или карту высот грузи с srgb: false: это ДАННЫЕ, они остаются линейными, это не цвет. Плоская нормаль, прочитанная через sRGB, отклоняется на ~35°. Встроенные lit / unlit сэмплят только цветную map, так что карта данных идёт в юниформ твоего собственного шейдера.

TypeScript
const scene = new Scene()
scene.add(Light.sun())
scene.open()

const main = async () => {
  const brick = await Material.load(asset('./brick.mat'))                        // шейдер с сэмплером normalMap
  brick.set('normalMap', await Texture.load(asset('./brick_n.png'), { srgb: false }))   // данные: остаются линейными
  scene.add(Mesh.box({ material: brick }))
}
main()
Note

Android и веб (Web Lite) хранят PNG/JPG как цвет, что бы ни говорил srgb; KTX2 несёт своё цветовое пространство в заголовке, так что карта данных, которая должна быть линейной везде, — это KTX2.

Сжатые текстуры для мобильных: KTX2

KTX2 (Basis Universal, определяется по содержимому, а не по расширению) при загрузке транскодируется в лучший сжатый формат, который есть у GPU (ASTC, BC7, ETC2 или BC3; несжатый RGBA8, где нет ни одного), и остаётся сжатым в VRAM, с цепочкой мипов из файла. Используй KTX2 для больших текстур на мобильных: 2K в RGBA8 с мипами стоит ~21 МБ, та же картинка в сжатом виде — ~5 МБ. Их делает lecodes assets doctor --ktx2; цветовое пространство KTX2 (sRGB или линейная карта данных) берётся из его собственного заголовка, что бы ни говорил srgb.

Текстура из сырых пикселей: Texture.fromPixels

TypeScript
Texture.fromPixels(width, height, data: Uint8Array, options?: {
  channels?: 1 | 2 | 3 | 4   // байт на пиксель; по умолчанию 4
  srgb?: boolean             // по умолчанию true (цвет); false = данные
}): Texture
tex.update(x, y, width, height, data: Uint8Array): void   // перезалить прямоугольник (то же число каналов)

Текстура из сырых байтов — построчно, width × height × channels, без мипов, копируется при вызове. fromPixels бросает исключение на хосте, где его нет, или когда data слишком короткий.

TypeScript
const scene = new Scene()
scene.add(Light.sun())
scene.open()

// шахматка 8×8, один байт на пиксель (серый)
const size = 8
const px = new Uint8Array(size * size)
for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) px[y * size + x] = (x + y) % 2 ? 255 : 40
const checker = Texture.fromPixels(size, size, px, { channels: 1 })
scene.add(Mesh.box({ material: Material.unlit({ map: checker }) }))

px.fill(255, 0, size)                      // позже: поменять верхнюю строку
checker.update(0, 0, size, 1, px.subarray(0, size))

Нарисованный канвас на 3D-поверхности: Texture.fromCanvas

TypeScript
Texture.fromCanvas(canvas: Canvas): Texture

Запекает поверхность Canvas в текстуру — синхронно, без декодирования. GPU-текстура кэшируется на канвасе, поэтому повторные вызовы (или несколько материалов) делят одну, а canvas.update() перезаливает её. Сам ты это зовёшь редко: присвоение Canvas в material.map (или Material.lit({ map: canvas })) делает это за тебя.

TypeScript
const scene = new Scene()
scene.add(Light.sun())
scene.open()

const label = new Canvas(256, 128)
label.fillStyle = '#1e293b'
label.fillRect(0, 0, 256, 128)
label.fillStyle = '#ffffff'
label.font = '48px sans-serif'
label.fillText('Score 0', 20, 80)
const sign = Mesh.box({ material: Material.unlit({ map: label }) })   // запекается в текстуру при присвоении
scene.add(sign)

// позже: нарисуй заново, потом
label.update()   // перезаливает текстуру, которую сэмплит материал
Note

material.map = canvas делает то же за один шаг (материал сам запекает канвас).

Размер и режим wrap (тайлинг): width, wrapS / wrapT

TypeScript
tex.width, tex.height     // пиксельные размеры (только чтение)
tex.wrapS = 0             // wrap по горизонтали (U): 0 clamp-to-edge, 1 repeat (по умолчанию), 2 mirrored repeat
tex.wrapT = 0             // wrap по вертикали (V), те же значения

wrapS / wrapT применяются, когда текстура присваивается юниформу материала, — задавай их до material.set('baseColorMap', tex) (или Material.lit({ map: tex })).

TypeScript
const scene = new Scene()
scene.add(Light.sun())
scene.open()

const main = async () => {
  const tiles = await Texture.load(asset('./tiles.png'))
  tiles.wrapS = 0      // clamp-to-edge по горизонтали
  tiles.wrapT = 2      // mirrored repeat по вертикали
  scene.add(Mesh.box({ material: Material.lit({ map: tiles }) }))   // задай wrap ДО присвоения
}
main()
Note

у Texture нет dispose(). Текстура освобождается сама, как только ты отпустишь все ссылки на неё И ни один материал её больше не сэмплит; пока материал её использует, она живёт. Грузи большие текстуры один раз и переиспользуй.

Настройки качества текстур: Texture.anisotropy / Texture.maxSize

TypeScript
Texture.anisotropy = 4    // анизотропная фильтрация, 1 (выкл) … 16 (с ограничением); по умолчанию 2
Texture.maxSize = 1024    // лимит размера текстуры в px, 0 = нет (по умолчанию)

Меню «качество текстур». Обе настройки действуют только на текстуры, привязанные или загруженные после того, как их задали, — загруженный уровень сохраняет свои текстуры, — так что задавай их до загрузки уровня (SceneOptions.anisotropy / maxTextureSize делают это заранее, см. Scene). При maxSize KTX2 теряет верхние уровни мипов при загрузке, а картинка glTF уменьшается; fullSize освобождает от лимита одну текстуру. Хост может зафиксировать любую из них (на десктопе CREATOR_TEXTURE_ANISOTROPY / CREATOR_TEXTURE_MAX_SIZE).

Видео на 3D-поверхности: VideoPlayer.texture

Текстуру нельзя создать из видеофайла напрямую — проигрывай его VideoPlayer и сэмпли его текстуру:

TypeScript
const player = new VideoPlayer(asset('./clip.mp4'))
const screen = Mesh.plane({ material: Material.video(player.texture) })

player.texture сообщает width/height равными 0 (размер видео неизвестен в момент создания текстуры). См. Медиа и Material.video.

Подводные камни

TypeScript
// ✗ скармливать 3D Texture в Sprite (или Texture2D в Material)
new Sprite({ texture: await Texture.load(url) })       // не тот движок — используй Texture2D.load
// ✓ каждый движок грузит свой тип
new Sprite({ texture: await Texture2D.load(url) })

// ✗ карта данных (нормали, маска, карта высот), загруженная как цвет, — читается искажённой через sRGB
material.set('normalMap', await Texture.load(asset('./brick_n.png')))
// ✓ material.set('normalMap', await Texture.load(asset('./brick_n.png'), { srgb: false }))

Смотрите также

  • Material — где текстуры потребляются (map, юниформы)
  • Texture2D — аналог для 2D-движка
  • Медиа — VideoPlayer.texture
  • Canvas — рисованные поверхности как текстуры