News | About | Download | Documentation | Development | Links

Loading graphics, ClanLib API overview

Abstract:

This document will discuss different ways to load graphics in ClanLib. Thereafter it will discuss methods to manipulate the images without too much effords.

This document expects that you have already read the Display Component document. If you haven't, please do that first.

Loading from files

Most ClanLib games will usually use resources to load its graphics, but we will start showing how the inner parts of the resource manager loads its graphics. Hopefully this should make it more clear how the whole stuff works.

To construct a surface or texture in ClanLib, we first need to load it into a surface provider. There are surface providers for many common image formats, including: CL_PCXProvider, CL_TargaProvider, CL_PNGProvider and CL_JPEGProvider.

To use these providers, simple create an instance of it, eg.

// Create a provider:
CL_PixelBuffer *provider = new CL_TargaProvider("image.tga");

// Load it (true = delete provider when surface is deleted):
CL_Surface *surface = new CL_Surface(provider, true);

Luckily, ClanLib provides a shortcut for the lazy among us. It can automatically figure out which provider to use based on the file-extension. Use it like this:

CL_Surface *surface2 = new CL_Surface("image.tga");

Loading from resources

Although the above loading mechanism in itself is quite simple, it is often far better to seperate the description of an image from the actual game code. Instead of specifying an image by its filename and type, you use an name making more sense for the game code.

CL_ResourceManager *resources = new CL_ResourceManager("resources.scr");

CL_Surface *surface = new CL_Surface("InGame/Level1/background", resources);

The image may be in any format supported by the ClanLib surface providers, and the resource description may include transparency, subarrays and other fancy stuff. The resources.scr file includes a description of the resource that may look like this:

section InGame
{
	section Level1
	{
		background = background1.tga ( // name and the file location
			type = surface,            // resource is surface
			tcol = (0, 1, 2, 3));      // four transparent colors.

		walking_man = man.pcx (type = surface);
	}
}

As you can probably see, the game code no longer needs to know how the resource is physically loaded. And it is possible to change the image without recompiling the application.

The resource manager may also be attached to something else than physical files, it may be loading them from a network server, or a datafile. The nice thing is that the game code doesn't know, and doesn't need to either.

If you want to load the image resource into a texture that is also possible:

CL_Texture *texture = new CL_Texture("InGame/Level1/background", resources);

If you want more information about resources, have a look at the resource overview.

Creating from scratch

TODO: Write about CL_Canvas