Class CL_Canvas

Detailed description:

For the OpenGL target, this object represents an OpenGL "pbuffer". A pbuffer is an off-screen OpenGL context that can function as hardware accelerated rendering to a canvas.

To use CL_Canvas, first create an instance of CL_Canvas. Then load a surface into the canvas. This will make ClanLib copy the contents of the surface (texture for GL) to the canvas. After this rendering operations can be performed on the canvas.

If the surface selected into the canvas is drawn, ClanLib will automatically upload the contents of the canvas back into the surface. Likewise if another surface is selected into the canvas the surface will be updated.

It is recommended to limit the amount of canvas objects in the application. Every canvas require construction of a new OpenGL context, and canvases consume frame buffer memory.

In Windows a pbuffer can get 'lost', meaning that the operating system can suddenly just use the memory for something else, without warning. Because of this it is adviced to keep data in the canvas for as little time as possible - sync_surface() can be used force uploading of the canvas' contents to the surface. Generally you do not need to do this since drawing the surface will force such an upload, but if the surface is not be drawn for some time, forcing an upload is a good idea.

If the pbuffer is lost, ClanLib will automatically try to reclaim the canvas and sync it with the latest version stored in the surface (the texture). As long as the pbuffer is lost, any drawing commands on the canvas will be silently ignored. This cannot guarantee never loosing what is drawn to the canvas, but at least not everything will be completely lost.

Example of usage:

CL_Surface surface_foo("foo.png");
CL_Surface surface_bar("bar.png");
CL_Canvas canvas;
canvas.select_surface(surface_foo);
surface_bar.draw(5, 5, canvas.get_gc());
canvas.get_gc()->draw_line(0, 0, 100, 100, CL_Color::yellow);
canvas.sync_surface();