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-тесты
ничего не декодируют и не проигрывают видео.
Обзор
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
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, так что карта данных идёт в юниформ твоего собственного
шейдера.
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()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
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 слишком короткий.
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
Texture.fromCanvas(canvas: Canvas): TextureЗапекает поверхность Canvas в текстуру — синхронно, без декодирования.
GPU-текстура кэшируется на канвасе, поэтому повторные вызовы (или несколько материалов) делят одну,
а canvas.update() перезаливает её. Сам ты это зовёшь редко: присвоение Canvas в material.map
(или Material.lit({ map: canvas })) делает это за тебя.
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() // перезаливает текстуру, которую сэмплит материалmaterial.map = canvas делает то же за один шаг (материал сам запекает канвас).
Размер и режим wrap (тайлинг): width, wrapS / wrapT
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 })).
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()у Texture нет dispose(). Текстура освобождается сама, как только ты отпустишь все ссылки на неё И
ни один материал её больше не сэмплит; пока материал её использует, она живёт. Грузи большие
текстуры один раз и переиспользуй.
Настройки качества текстур: Texture.anisotropy / Texture.maxSize
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 и сэмпли его
текстуру:
const player = new VideoPlayer(asset('./clip.mp4'))
const screen = Mesh.plane({ material: Material.video(player.texture) })player.texture сообщает width/height равными 0 (размер видео неизвестен в момент создания
текстуры). См. Медиа и Material.video.
Подводные камни
// ✗ скармливать 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 }))