MoonWorks-docs/content/Graphics/Resources/Texture.md

title	date	weight
Texture	2021-01-25T14:59:49-08:00	2

Textures are containers for pixel data. They always have a width, height, and color format. The most simple and common kind of texture is just a 2D texture. But textures can also have depth (3D textures), multiple layers (cubemaps), multiple resolution levels (mipmap levels), or a multisample count. Describing the use cases for all of these is beyond the scope of this tutorial, but they should come up as you learn how to execute certain rendering techniques.

To create a new texture resource, you can set up a TextureCreateInfo struct:

var textureCreateInfo = new TextureCreateInfo
{
    Width       = 128,
    Height      = 128,
    Depth       = 1,
    Format      = TextureFormat.R8G8B8A8,
    IsCube      = false,
    LevelCount  = 1,
    SampleCount = SampleCount.One,
    UsageFlags  = TextureUsageFlags.Sampler
};

var myTexture = new Texture(GraphicsDevice, textureCreateInfo);

This sets up 128x128 2D Texture that uses 32 bits per pixel: 8 bits each for red, green, blue, and alpha. We also indicate that we intend to use the texture for sampling.

To put pixels in the texture, we use the SetTextureData method on a command buffer.

var pixels = new Color[width * height];

// put data in the pixel array here!

myCommandBuffer.SetTextureData(myTexture, pixels);

We'll get to command buffers later, just know that you must upload data via command buffer so that you can safely use multithreading. This can speed up load times greatly.

Of course, having to fill in all this data every time is kind of cumbersome, so we have some shortcut methods for common texture usages.

var my2DTexture = Texture.CreateTexture2D(GraphicsDevice, 128, 128, TextureFormat.R8G8B8A8, TextureUsageFlags.Sampler);
var my3DTexture = Texture.CreateTexture3D(GraphicsDevice, 128, 128, TextureFormat.R8G8B8A8, TextureUsageFlags.Sampler);
var myCubeTexture = Texture.CreateTextureCube(GraphicsDevice, 128, TextureFormat.R8G8B8A8, TextureUsageFlags.Sampler);

There is also a built-in PNG loader that creates a 2D R8G8B8A8 texture and fills it with pixel data.

var myPNGTexture = Texture.LoadPNG(GraphicsDevice, myCommandBuffer, "coldsteel_the_hedgehog.png");

One last concept we should discuss before moving on is texture slicing.

Texture slices are a very commonly used concept in MoonWorks. You don't have to do texture operations on an entire texture - you can instead use a subsection of the texture for whatever your operation is.

var myTexture = Texture.LoadPNG(GraphicsDevice, myCommandBuffer, "myTexture.png");
var mySliceRect = new Rect(0, 0, 16, 16);
var myTextureSlice = new TextureSlice(myTexture, mySliceRect);

This code produces a texture slice which is a 16x16 square in the top left corner of the image. You can create slices of 3D textures and cube textures as well! We'll talk more about where to use texture slices later.