engine/docs/en/graphics/texture/texture.md

order, title, type, group, label

order	title	type	group	label
0	Texture Overview	Graphics	Texture	Graphics/Texture

Textures (Texture) are one of the most commonly used resources in 3D rendering. When shading a model, we need to set a color value for each fragment. Besides setting the color value manually, we can also choose to read texels from a texture for shading to achieve richer artistic effects.

It is worth noting that images, canvas, raw data, videos, etc., can all be used as textures. The Galacean engine currently supports all WebGL standard textures.

We will find that many issues in the engine stem from mapping between different spaces (such as MVP transformations). Textures are no exception. Developers need to understand the mapping relationship from image space to texture space and the mapping rules from texels to pixels.

This article will mainly introduce:

• Types of textures, texture space, and common properties
• 2D Textures
• Cube Textures
• Playing Videos through Textures
• Setting Sky Textures
• Off-screen Rendering Textures
• Using Compressed Textures

Texture Types

Type	Description
2D Textures	The most commonly used artistic resource, sampled using 2D UV coordinates
Cube Textures	Composed of 6 2D textures, can be used to achieve skybox, environment reflection effects
2D Texture Arrays	Occupies only one texture unit, very suitable for implementing texture atlas switching needs

Texture Space

Texture space is determined by the shape of the texture. 2D textures require 2D space vectors for texture sampling, while cube textures require 3D space vectors for texture sampling.

Texture 2D

Texture Cube

Common Properties

Although there are various types of textures, they all have some similar basic properties and settings:

Property	Value
Wrap Mode U (wrapModeU)	Clamp Mode (Clamp), Repeat Mode (Repeat), Mirror Repeat Mode (Mirror)
Wrap Mode V (wrapModeV)	Clamp Mode (Clamp), Repeat Mode (Repeat), Mirror Repeat Mode (Mirror)
Filter Mode (filterMode)	Point Filter (Point), Bilinear Filter (Bilinear), Trilinear Filter (Trilinear)
Anisotropic Filter Level (anisoLevel)	1 ~ 16, depending on device support

Loop Mode

The texture sampling range is [0,1]. When the texture UV coordinates exceed this range, we can control how the exceeding part is sampled by setting the loop mode.

Sampling Loop Mode	Explanation
Clamp	Samples the edge texel when out of range
Repeat	Resamples from [0,1] when out of range
Mirror	Mirrors sampling from [1,0] when out of range

Filter Mode

Generally, texels and screen pixels do not correspond exactly. We can control the filtering mode in magnification (Mag) and minification (Min) modes by setting the filter mode.

Sampling Filter Mode	Explanation
Point	Uses the texel closest to the sampling point
Bilinear	Uses the average value of the nearest 2*2 texel matrix
Trilinear	Applies average filtering to the mipmap levels based on bilinear filtering

Anisotropic Filtering Level

Anisotropic filtering technology can make textures appear clearer when viewed at oblique angles. As shown in the figure below, the end of the texture becomes clearer as the anisotropic filtering level increases. However, use it with caution; the higher the value, the greater the GPU computation.

General Settings

Setting	Value
mipmap	Multi-level texture gradient (enabled by default)
flipY	Flip Y-axis (disabled by default)
premultiplyAlpha	Premultiply alpha channel (disabled by default)
format	Texture format (default R8G8B8A8)

mipmap

The engine enables mipmap (multi-level texture gradient) by default. Mipmap is used to solve the precision and performance issues when sampling high-resolution textures on low-resolution screens, allowing the selection of different resolution textures at appropriate distances, as shown below:

It should be noted that WebGL2.0 supports textures of any resolution and will generate mip levels based on the mipmap algorithm. However, if your environment is WebGL1.0, please ensure to upload power-of-two textures, such as textures with a resolution of 1024 * 512. Otherwise, Galacean will detect that the environment cannot use mipmap and will automatically downgrade to disable the mipmap function, which may cause some unexpected visual effects.

If you need to change the default behavior of mipmap, you can do so via script. For parameters, see API:

const texture = new Texture2D(
  engine,
  width,
  height,
  TextureFormat.R8G8B8A8,
  false
); // 第 5 个参数

For cube texture scripts, see API:

const cubeTexture = new TextureCube(
  engine,
  size,
  TextureFormat.R8G8B8A8,
  false
); // 第 4 个参数

flipY

flipY is used to control whether the texture is flipped along the Y-axis, i.e., upside down. The engine and editor disable it by default. If you need to change the default behavior of flipY, you can do so via the setImageSource method:

const texture = new Texture2D(engine, width, height);
texture.setImageSource(img, 0, true); // The 3rd parameter

premultiplyAlpha

premultiplyAlpha is used to control whether the texture pre-multiplies the alpha (transparency) channel. The engine and editor have it turned off by default. If you need to change the default behavior of premultiplyAlpha, you can do so through the setImageSource method:

const texture = new Texture2D(engine, width, height);
texture.setImageSource(img, 0, undefined, true); // The 4th parameter

format

The engine uses TextureFormat.R8G8B8A8 as the default texture format, meaning that the red, green, blue, and alpha channels each use 1 byte, allowing each channel to store color values ranging from 0 to 255. The engine supports configuring different texture formats, which can be referenced in TextureFormat. For example, if we do not need to use the alpha channel, i.e., the A channel, we can use TextureFormat.R8G8B8:

const texture = new Texture2D(engine, width, height, TextureFormat.R8G8B8);