One very used aspect in any game is drawing 2D images. To do this, ClanLib provides three lowlevel interfaces:
The CL_Target class in ClanLib represents some image data that can be accessed and modified.
To access the memory, you must call CL_Target::lock() and then afterwards use CL_Target::get_data() to get a pointer to the image data. When you are done modifying the image, you must call CL_Target::unlock().
Besides the above data access mechanism, the CL_Target interface also contain a set of commonly used drawing functions. Examples of this is drawing lines, boxes and blitting from target to target. All of those functions respect the clipping functions also included in CL_Target.
To implement your own target, you have to inherit all the abstract functions and implement them - but in most cases you will probably prefer to use the CL_Canvas implementation. It simply creates a target in the size and format that you specify in the constructor.
In order to draw images to the screen, you have to load them into a surface. A surface analyzes and stores the iamge in a format more suitable for the graphics card. This is done to maximize the performance and take advantage of whatever technology a platform offers.
A surface loads its image data from a surface provider. A surface provider is actually just a CL_Target with some additonal functions that describe how it should blit this data. For instance, a surface provider also contain a function that describes if one of the colors in the image is a transparent (source colorkey), and should be handled as transparent when being blitted.
It is not possible to access the data in a surface. If you need to alter the data in a surface, change it using the CL_Target and CL_Canvas interfaces and reload it into the surface. Unlike most surfaces in other 2D libraries, we simply do not allow this because we need the freedom to store the image in whatever format(s) that suits the platform. This is for performance reasons, and allows us to upload the surface to Pixmap, OpenGL textures and seperate alpha from the other color components in an image.
On some platforms it can be a rather expensive thing to create or reload a surface. This can either be caused by our image analysis or the display target being used. For images that changes frequently, you may want to use a dynamic surface instead (use CL_Surface::create_dynamic() instead of CL_Surface::create()). The difference is that a dynamic surface doesn't analyze the image, and doesn't try to store it in a smarter format. A dynamic surface will instead access the surface provider in every blit and just try to draw it as quickly as possible.
The downside of dynamic surfaces is that if you draw an image often without changes, it will be significant slower.