Textures and render textures

AdvancedProgrammer

Xenko uses the Texture class to interact with texture objects in code.

For more information about rendering to a texture, see Render textures.

Load a texture

To load a texture from an asset in Xenko, call this function:

  1. // loads the texture called duck.dds (or .png etc.)
  2. var myTexture = Content.Load<Texture>("duck");

This automatically generates a texture object with all its fields correctly filled.

Create a texture

You can also create textures without any assets (eg to be used as render target). To do this, call the constructor of the Texture class. See the Texture class reference to get the full list of available options and parameters. Some texture formats might not be available on all platforms.

Code: Create a texture

  1. var myTexture = Texture.New2D(GraphicsDevice, 512, 512, false, PixelFormat.R8G8B8A8_UNorm, TextureFlags.ShaderResource);

Render textures

Create a render target

The GraphicsPresenter class always provides a default render target and a depth buffer. They are accessible through the BackBuffer and DepthStencilBuffer properties. The presenter is exposed by the Presenter property of the GraphicsDevice. However, you might want to use your own buffer to perform off-screen rendering or post-processes. As a result, Xenko offers a simple way to create textures that can act as render textures and a depth buffers.

Code: Create a custom render target and depth buffer

  1. // render target
  2. var myRenderTarget = Texture.New2D(GraphicsDevice, 512, 512, false, PixelFormat.R8G8B8A8_UNorm, TextureFlags.ShaderResource | TextureFlags.RenderTarget);
  4. // writable depth buffer
  5. var myDepthBuffer = Texture.New2D(GraphicsDevice, 512, 512, false, PixelFormat.D16_UNorm, TextureFlags.DepthStencil);
Note

Don't forget the flag RenderTarget to enable the render target behavior.

Make sure the PixelFormat is correct, especially for the depth buffer. Be careful of the available formats on the target platform.

Use a render target

Once these buffers are created, you can can easily set them as current render textures.

Code: Use a render target

  1. // settings the render textures
  2. CommandList.SetRenderTargetAndViewport(myDepthBuffer, myRenderTarget);
  4. // setting the default render target
  5. CommandList.SetRenderTargetAndViewport(GraphicsDevice.Presenter.DepthStencilBuffer, GraphicsDevice.Presenter.BackBuffer);
Note

Make sure both the render target and the depth buffer have the same size. Otherwise, the depth buffer isn't used.

You can set multiple render textures at the same time. See the overloads of SetRenderTargets(Texture, Texture[]) and SetRenderTargetsAndViewport(Texture, Texture[]) method.

Note

Only the BackBuffer is displayed on screen, so you need to render it to display something.

Clear a render target

To clear render textures, call the Clear(Texture, Color4) and Clear(Texture, DepthStencilClearOptions, Single, Byte) methods.

Code: Clear the targets

  1. CommandList.Clear(GraphicsDevice.Presenter.BackBuffer, Color.Black);
  2. CommandList.Clear(GraphicsDevice.Presenter.DepthStencilBuffer, DepthStencilClearOptions.DepthBuffer); // only clear the depth buffer
Note

Don't forget to clear the BackBuffer and the DepthStencilBuffer each frame. If you don't, you might get unexpected behavior depending on the device. If you want to keep the contents of a frame, use an intermediate render target.

Viewport

SetRenderTargetAndViewport(Texture, Texture) adjusts the current Viewport to the full size of the render target.

If you only want to render to a subset of the texture, set the render target and viewport separately using SetRenderTarget(Texture, Texture) and SetViewport(Viewport).

You can bind multiple viewports using SetViewports(Viewport[]) and SetViewports(Int32, Viewport[]) overloads for use with a geometry shader.

Code: Set the viewports

  1. // example of a full HD buffer
  2. CommandList.SetRenderTarget(GraphicsDevice.Presenter.DepthStencilBuffer, GraphicsDevice.Presenter.BackBuffer); // no viewport set
  4. // example of setting the viewport to have a 10-pixel border around the image in a full HD buffer (1920x1080)
  5. var viewport = new Viewport(10, 10, 1900, 1060);
  6. CommandList.SetViewport(viewport);

Scissor

The SetScissorRectangle(Rectangle) and SetScissorRectangles(Rectangle[]) methods set the scissors. Unlike the viewport, you need to provide the coordinates of the location of the vertices defining the scissor instead of its size.

Code: Set the scissor

  1. // example of setting the scissor to crop the image by 10 pixel around it in a full hd buffer (1920x1080)
  2. var rectangle = new Rectangle(10, 10, 1910, 1070);
  3. CommandList.SetScissorRectangles(rectangle);
  5. var rectangles = new[] { new Rectangle(10, 10, 1900, 1060), new Rectangle(0, 0, 256, 256) };
  6. CommandList.SetScissorRectangles(rectangles);

See also