Getting started

This guide will show you how to get started with the Apos.Shapes library.

Before you start, make sure that you have a valid MonoGame project. You can create a new project by following this other guide.

You can run this example directly in your browser here.

Install

Install using the following dotnet command:

dotnet add package Apos.Shapes

You can find other ways to install it on the NuGet page.

The library ships with a precompiled shader that is embedded in its assembly. Nothing gets added to your content pipeline and no shader compiler (or Wine on Linux / macOS) is needed. The minimum supported MonoGame version is 3.8.2.

Setup

Import the library with:

using Apos.Shapes;

In your game’s constructor, set the GraphicsProfile to HiDef. (If you’re using this library with KNI, set it to FL10_0 instead.) This enables the features that the shader will use. By default, MonoGame uses the Reach profile.

public Game1() {
    _graphics = new GraphicsDeviceManager(this);

    _graphics.GraphicsProfile = GraphicsProfile.HiDef;
}

In your game’s LoadContent(), create a ShapeBatch instance:

protected override void LoadContent() {
    _sb = new ShapeBatch(GraphicsDevice);
}

ShapeBatch _sb;

The constructor warms up the shader, which gets the driver to compile it as early as possible instead of on the first frame that draws. It presents a frame to do that, so if your game already has something on screen, you can turn it off and call Warmup() when you’re ready:

_sb = new ShapeBatch(GraphicsDevice, warmup: false);

The shader comes in a smaller version for each mix of dashes, gradients, and text, and each one compiles the first time something draws with it. Flat colors need the smallest one, which is what the constructor warms up. If your game draws text with gradients, you can warm up that version too:

_sb.Warmup(ShapeFeatures.Text | ShapeFeatures.Gradients);

A batch draws with the version that has everything in it, so name the features your game draws together. Once a version has compiled, a batch that needs less keeps using it instead of waiting on a smaller one.

In your game’s draw loop, call Begin and End and do your drawing between those two calls:

protected override void Draw(GameTime gameTime) {
    GraphicsDevice.Clear(Color.Black);

    _sb.Begin();

    _sb.FillCircle(new Vector2(200, 100), 50, Color.White);

    _sb.End();

    base.Draw(gameTime);
}

Everything that is drawn within the Begin and End calls will be batched together.

Follow up

Shapes, a page that lists every shape that the ShapeBatch can draw.