Manual

Manual

Textures

A texture is an image the GPU draws with: on a material, as a sprite or in an interface. This page covers the image files Abyss reads, each import setting and what it changes, the formats compression picks, and how a game makes and reads images of its own from code.

Image files

Put images anywhere in your project's assets/ folder. The editor reads these:

FormatExtensions
PNG.png
JPEG.jpg, .jpeg
BMP.bmp
TGA.tga
WebP.webp, lossy or lossless, with its alpha; an animated WebP imports its first frame

In the Project panel, an image's tile is a small picture of it. Pixel art stays crisp there, each pixel enlarged whole. Drag an image onto a material's texture slot to draw with it (see Meshes and materials), or set it to the Sprite type to draw it in 2D.

How a texture is imported

Your image file stays as you painted it. What the GPU is given is imported from it into the project's cache/ folder: no larger than its Max Size, with its mipmaps, and compressed. A texture is imported again only when its file or its settings change, in the background, and the scene swaps in the new import when it lands. Importing explains the cache, the spinner on a tile and the status bar.

Pick an image in the Project panel and the Inspector shows its import settings, headed with its name and texture importer. Change them, then click Apply to import it again, or Revert to go back. The editor asks about settings you changed and did not apply before the Inspector shows something else, and before you quit.

A texture nobody has configured imports with mipmaps, at a Max Size of 2048, filtered bilinearly, repeating at its edges, and compressed at Normal Quality. Its sidecar holds only the settings you change, so the defaults never clutter a diff.

The import settings

The settings are in four sections, each headed as below. A preview of the import follows them.

Texture

Texture Type says what the image is for. Picking a type also sets the settings it starts with: a sprite gets no mipmaps and clamps at its edges, and every other type gets mipmaps and repeats.

Texture TypeUse it for
DefaultA picture: a material's base color, an emissive map
Normal MapA normal map. Its numbers are read as numbers, never as color.
Sprite (2D and UI)An image drawn at its own size in 2D or in an interface
Single ChannelOne channel of numbers, a byte a texel: a mask, a height map, a roughness map. Only the image's red is kept.

A sprite adds two settings here: Sprite Mode, Single for the whole image or Multiple to cut it into slices, and Pixels Per Unit, how many of its pixels make a meter. With Multiple, the Sprite Editor button opens the image to cut. Sprites covers both.

sRGB (Color Texture) is on for colors you see, which the GPU decodes from sRGB as it samples them. Turn it off for an image of numbers a shader reads, such as a metallic-roughness map or a mask. It is grayed for a Normal Map and a Single Channel, which are numbers either way.

Mipmaps

Mipmaps are the texture again at half size, a quarter, and so on down to one texel, so a texture far away is drawn from a smaller level instead of shimmering. They take a third more memory.

SettingWhat it does
Generate MipmapsMakes every smaller level. Off for a sprite or an interface's image, which is drawn at its own size.
Mipmap FilteringHow each level is made from the one above: Box, the average of each two by two, soft and right for most textures; or Kaiser, sharper as it shrinks, at the cost of a little ringing.

Mipmaps of color are made in linear light, so a checkerboard of black and white fades to the gray it looks like rather than a darker one. A repeating texture's mipmaps wrap at their edges as it does, so its smaller levels still tile.

Sampling

SettingWhat it does
Filter ModePoint (no filter) takes the nearest texel and the nearest mipmap, which pixel art wants. Bilinear blends between texels. Trilinear blends between texels and between mipmaps too, so the step from one mipmap to the next does not show.
Aniso Level1 to 16: how many samples a surface seen at a slant takes, which keeps a floor sharp into the distance. Grayed for Point.
Wrap ModeWhat the texture does past its edges: Repeat tiles it, Clamp carries the edge texel on, and Mirror tiles it flipped every other time.

A change of Filter Mode or Aniso Level applies at once, without importing again.

Size and Compression

SettingWhat it does
Max SizeThe longest side the import may have, from 32 to 8192. A larger image is brought down to it, keeping its shape: 4096 by 1024 at a Max Size of 2048 imports at 2048 by 512.
CompressionNone, Low Quality, Normal Quality or High Quality. See Compression.
FormatWhat the GPU was given at the last import, its size and its memory, such as BC1 sRGB · 2048 × 2048 · 2.7 MB.

The preview

Under Apply and Revert is the import itself, not the source, so you see what Max Size and compression did. The buttons above it show its color (RGB) or one channel as gray (R, G, B or A), and the slider picks a mipmap. The line under it gives its size beside the source's, its format, its mipmaps and its memory.

Compression

A compressed texture is kept on the GPU in blocks of four by four texels, which the hardware decodes as it samples: a quarter or an eighth of the memory, for a little of its detail. The format follows from the texture's type, its Compression, and whether any of it is see-through:

TextureNoneLow or Normal QualityHigh Quality
Default or Sprite, every texel opaqueRGBA8, 4 bytes a texelBC1, half a byteBC7, 1 byte
Default or Sprite, with transparencyRGBA8, 4 bytesBC3, 1 byteBC7, 1 byte
Normal MapRGBA8, 4 bytesBC5, 1 byteBC5, 1 byte
Single ChannelR8, 1 byteBC4, half a byteBC4, half a byte
  • Normal Quality, the default, suits most textures.
  • High Quality keeps a picture nearer what you painted, for the same memory as BC3, and takes longer to import.
  • Low Quality picks the same formats as Normal Quality, the smallest a desktop GPU has.
  • None keeps every texel as you painted it. Use it where an image must stay exact, such as one your code reads with PixelsOf.

A normal map compressed as BC5 keeps only its X and Y, and its Z is worked out from them as it is drawn. A compressed texture's sides are brought up to a multiple of four, which the GPU requires.

Transparent edges

The clear pixels of an image with transparency still hold a color nobody sees, often white or black. A smoothly filtered texture blends that color into the edge beside them, which draws a light or dark rim round a cut-out, in every mipmap.

So when an image of color has transparency, the import gives each fully clear pixel the color of what shows nearest it, keeping it clear, and its mipmaps and a Max Size brought down weigh each pixel's color by how much of it shows. You do not have to paint the clear pixels yourself. An image with sRGB off, a normal map and a single channel are left as they are, as their alpha may be any number.

Several images at once

Pick several images in the Project panel, and nothing else, to edit their settings together. The Inspector is headed with how many and names them. Each setting shows the first image's value, and a dash where any of the others differs. A change is made in every image, each taking what its own type brings, so making them all Sprite takes the mipmaps off each. Apply writes every image you changed and imports each again, and Revert puts every one back.

Sprite Mode and Pixels Per Unit show once every image picked is a sprite. The preview, the Format line and the Sprite Editor are shown only for one image at a time.

Textures in a built game

A build packs each texture as it was imported, mipmaps and compressed blocks included, so a built game decodes nothing as it loads. Only the editor imports: a game played from its folders with dotnet run reads its images from their source files instead, filtered and wrapped as their settings say, but neither compressed nor brought down to their Max Size.

An image your code loads by name has to be addressable, and its key has the type ImageAddress:

ImageId coin = context.Assets.LoadImage(Addresses.Icons.Coin);

See Addresses and labels for keys, and Build and run your game for what a build writes.

Pictures from pixels

A game can also draw pictures of its own: a minimap, a noise texture, a color ramp, an atlas composed from several images. Such an image is an ordinary one: a material's texture slot takes it, and changing its pixels changes it for every material drawn with it.

Make and change an image

CreateImage takes 8-bit RGBA pixels, four bytes a pixel, row by row from the top left, up to 8192 on a side. The pixels are copied, so your array is yours again once it returns. Say ImageColor.Linear for numbers rather than colors, such as a normal map or a mask.

byte[] pixels = new byte[128 * 128 * 4];    // red, green, blue, alpha for each pixelbyte[] mask = new byte[128 * 128 * 4];// ... fill them
ImageId minimap = context.Assets.CreateImage(128, 128, pixels);                   // colors, sRGBImageId holes = context.Assets.CreateImage(128, 128, mask, ImageColor.Linear);    // numbersMaterialId screen = context.Assets.CreateMaterial(MaterialSpec.Default.WithTexture(minimap.Value));
// Later, as often as it changes, at any size:context.Assets.UpdateImage(minimap, 128, 128, pixels);

UpdateImage keeps what the image is, sRGB or linear, and how it is drawn. Every material using the image draws the new pixels from the next frame. It works on an image loaded from a file too, which is then no longer that file's. When you no longer need an image, context.Assets.Release(image) lets it go; it stays while a material still uses it. Meshes and materials covers materials and giving them to entities.

How it is drawn

An image made from pixels starts blended, tiled and with no mipmaps. SetImageSampling says otherwise, and keeps saying it for every pixels UpdateImage gives it later:

context.Assets.SetImageSampling(atlas, new ImageSampling{    Filter = ImportFilter.Point,   // pixel art: the nearest texel    Wrap = ImportWrap.Clamp,    MipLevels = 5,                 // its own size and four smaller, then stop});
FieldWhat it says
FilterPoint, Bilinear or Trilinear, as Filter Mode does
WrapRepeat, Clamp or Mirror, as Wrap Mode does
Anisotropy1 to 16, as Aniso Level does; more than 1 needs a blended filter
MipLevelsHow many levels, its own counted: 1 for no mipmaps, 0 for every level down to one texel

The mipmaps are made from its pixels each time, each level the average of the two by two above it in linear light, weighted by alpha so a cut-out's clear pixels do not darken its edge. An atlas of tiles stops its mipmaps while a tile is still a few texels wide, so tiles never run into each other: 5 levels for tiles of 16. An image loaded from a file is drawn as its import settings say, and SetImageSampling refuses it.

Read a texture's pixels

PixelsOf reads the first level of any image, made in code or loaded from a file, as four bytes a texel. An imported texture is decoded from its compressed blocks, so what you read is what is drawn, in the editor and in a built game alike. Import an image with Compression set to None to read the very pixels you painted. A single channel reads as its red.

schedule.AddFlow("Atlas", async flow =>{    ImageId grass = flow.Assets.LoadImage(Addresses.Blocks.Grass);    if (await flow.Loaded(grass) != AssetState.Loaded)    {        return;    }
    ImagePixels read = flow.Assets.PixelsOf(grass);    byte red = read.At(0, 0)[0];          // the top left texel: red, green, blue, alpha    // ... copy read.Rgba into a larger array, then make the atlas of it with CreateImage});

A load must have finished before PixelsOf: wait for it in a flow with flow.Loaded, or check context.Assets.StateOf(image) in a system. For smooth noise to fill an image with, see Random numbers and noise.

In the Scripting API