16.2 Surfaces

In ClanLib images are associated with surfaces, and surfaces are encapsulated into a CL_Surface class. Conceptually, a surface is a rectangular block of bytes in memory. Surfaces can hold any type of information, but usually programmers will use them to hold image information, such as images loaded from files. Those who have used Photoshop, GIMP, or other image editing applications will probably be familiar with the concept of layers; the idea of a surface is similar. Like clear sheets of plastic stacked atop a background, surfaces can hold all kinds of images, and additionally ClanLib equips surfaces with the ability to draw their contents on the display.

In ClanLib, a CL_Surface object can be created in numerous ways, but perhaps the simplest is to create a surface directly from an image file. This method will create a surface object and load the contents of the image file into the surface, ready to display. Consider the following code:

      CL_Surface *Surface = new CL_Surface("Image01.png");

Thus, in a single line a surface is created with a loaded image. The following list contains all the constructors for CL_Surface; some of these are explained in detail later.

CL_Surface();
CL_Surface(CL_PixelBuffer provider, int flag = flag_none);
CL_Surface(const std::string& resource_id, CL_ResourceManager* Manager);
CL_Surface(const std::string& filename, int flag = flag_none);
CL_Surface(const CL_Surface& copy);

Note

ClanLib surfaces support the following image formats: JPEG, PNG, PCX, and TGA.

A loaded surface can then be drawn on the display in any frame using the draw method. By frame, I mean inside a Paint, or UpdateFrames, function called during the message loop (see the previous chapter). Consider the following code:

      void cClanLibApp::Paint()      {         CL_Display::clear(CL_Color(255,0,0));         Surface->draw(0,0);      }

The draw method draws the surface on the display at the (x, y) coordinate location specified, with the origin (0,0) being at the top-left corner of the screen. Positive values of x move the image to the right, positive values of y move the image downward toward the bottom of the screen, and negative values for x and y move the image left and upward, respectively.