2D Texture

2D textures (Texture2D) are the most commonly used artistic resources, sampled using 2D UV coordinates.

Creation

In the editor, you can easily import a 2D texture by following the steps:
Assets Panel -> Right-click Upload -> Select Texture2D -> Choose the corresponding texture -> 2D texture asset creation is complete.

Similarly, in scripts, you can load an image and obtain the corresponding 2D texture using the ResourceManager:

engine.resourceManager
  .load({
     type: AssetType.Texture2D,
     url: `image_url`,
  })
  .then((texture2D) => {
    // The texture can now be applied to materials or used for other operations
  });

Methods

setImageSource

As mentioned earlier, image-related data sources such as images, canvas elements, and videos can be used as textures. For example, a video can be uploaded to a texture using the setImageSource method:

// Get the video element (HTMLVideoElement)
const video = document.getElementsByTagName("video")[0];
 
// Load it into the texture
texture.setImageSource(video);

setImageSource only synchronizes the data of the current frame. Since video frames change continuously, you need to execute this in the onUpdate hook of the script to synchronize the texture with the video.

For scenarios like videos that require frequent updates to texture content, it is recommended to disable mipmap and set the texture usage to Dynamic when creating the texture for better performance.

setPixelBuffer

At the core, a texture corresponds to the color values of each pixel, i.e., RGBA channels. You can manually set these color values and upload them to the texture using the setPixelBuffer method:

const texture = new Texture2D(engine, 1, 1);
// Set the pixel to red, i.e., R channel to 255.
const data = new Uint8Array([255, 0, 0, 255]);
texture.setPixelBuffer(data);

getPixelBuffer

Similarly, you can retrieve the color data of these channels:

const texture = new Texture2D(engine, width, height);
// Perform a series of operations on the texture
// ...
// An array to store the color information, its size matches the amount of data to be read
const data = new Uint8Array(width * height * 4);
texture.getPixelBuffer(0, 0, width, height, 0, data);

Usage

Assigning a texture to the corresponding property of a material enables different rendering features. For example, adding a base color texture determines the base tone of the model. In the editor, you can simply select the corresponding texture for the property.

Similarly, in scripts, you can set it like this:

const material = new PBRMaterial(engine);
const texture = createTexture(); // As shown above, not repeated here
 
material.baseTexture = texture;

Color Bleeding

To solve the issue of black edges appearing at areas with abrupt alpha value changes in images with transparent pixels, the editor includes a color bleeding feature. This feature rewrites the RGB values of all transparent pixels in the image to match the RGB values of the nearest non-transparent pixel, effectively removing black edges from the image.