Tutorial – Loading Images

In this tutorial we will load images and display them.

Ensure you've covered 'Getting Started' before following this guide.

These tutorials are written assuming that the program is running on NET Core 3.0. The libraries themselves are NET Standard 2.1 compliant. If you don't have .NET Core 3.0 (or newer), then you can download it here.

Files

Before we can load an image, we must discuss one of the methods to access files in Heirloom. Heirloom provides a utility class called Files. This is a static class that provides uniform access to both embedded files and files on disk. Of course, you can use the C# standard library functionality if you prefer. Most resources can be loaded from System.IO.Stream.

Embedded Files

Embedded files are normalized into "identifiers", and thus behave differently than files on disk. Accessing assets through Files attempts to normalize this process by converting standard paths into the identifier form.

For example files/myImage.png becomes files.myimage.png. Then using this identifier it will look up the embedded file and open a stream. This short identifier is a bit of a trick. Files embedded in C# include the default namespace. Each embedded file may have multiple identifiers. Any one embedded file will typically have two identifiers. A full namespace version and a truncated version with the namespace removed. For the above example file the full identifier might have been company.gameproject.files.myimage.png. If the assembly embedding this file contains the namespace Company.GameProject,the namespace portion is truncated and you're left with files.myimage.png as seen above.

Disk Files

Files on disk (ie, regular files) can also be loaded using the Files utilities as well. If the path does not match an embedded resource, the system will then check for the file on disk.

Loading Images

Now that we have an idea how to access files, we can load an image.

var image = new Image("my/path/to/img.png");

Thats it! Note this is a shortcut for loading with the Files utility.

var image = new Image(Files.OpenStream("my/path/to/img.png"));

Drawing Images

Lets load this image!

(More free game assets can be found at Kenney)

Download and place the image in your project folder in a path like <project>/files/colored_castle.png. Then select this file in your visual studio project and in the properties tab change its build action to embedded resource.

public static class ImageExample
{
    public static Image MyImage;

    public static void Main(string[] args) 
    {
        Application.Run(() =>
        {
            // Construct the window
            var window = new Window("Image Example");
            window.MoveToCenter();

            // Load image
            MyImage = new Image("files/colored_castle.png");
            window.Size = MyImage.Size; // fit window to image

            // Create render loop
            var loop = RenderLoop.Create(window.Graphics, OnDraw);
            loop.Start();
        });
    }

    private static void OnDraw(Graphics gfx, float dt)
    {
        gfx.DrawImage(MyImage, Vector.Zero);
    }
}