--- name: "CL_Surface" section: "3" platform: "linux" package: "clanlib0-common-dev" version: "0.4.4-8" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/CL_Surface" --- # CL\_Surface(3) Image class in ClanLib. ## NAME CL\_Surface - Image class in ClanLib. ## DESCRIPTION This class is used to draw 2D images onto the backbuffer or to a renderer target. In ClanLib, a surface is understood to be an image represented in a form, where it is most suitable for as fast rendering as possible. Unlike many other libraries, it is not possible to get direct access to the surface data. A surface uses a surface provider to load its data. It is passed at creation time, and you can either roll your own provider, or use one already available in ClanLib. It is also possible to create a surface from a resource source. This will allow you to load an image using a resource ID instead of directly specifying the image in your source code. Dynamic surfaces If you have an image which changes very frequently (eg. each frame), you want to use a dynamic surface instead. The difference is that the surface won't cache the image, and it won't convert it to another image format more suitable for the display target. Note that this is only faster if you change your image very frequently - otherwise a normal surface is the best solution. When constructing your own images, you will most likely find the canvas surface provider interesting. This class will make it easier to create a custom drawing area where you can draw your image. All surfaceproviders is a renderer target. However, most of the normal surface providers are "read only", meaning that their image data will only remain intact during a lock session. This is because the providers consume less memory when the image is only available, when someone needs it. Only the canvas provider will not destroy the image. A surface can blit (draw itself) itself to the backbuffer, or to a renderer target. This means that you can use the surface to draw one surface provider to another. ## CLASS MEMBERS - static CL\_Surface \***load**( ``` const char *resource_id, CL_ResourceManager *manager) ``` - static CL\_Surface \***create**( ``` CL_SurfaceProvider *provider, bool delete_provider=false) ``` - virtual void **reload**() - virtual CL\_SurfaceProvider \***get\_provider**() - virtual void **put\_screen**( ``` int x, int y, int spr_no=0, CL_DisplayCard *card=NULL) ``` - virtual void **put\_screen**( ``` int x, int y, float scale_x, float scale_y, int spr_no=0, CL_DisplayCard *card=NULL) ``` - virtual void **put\_screen**( ``` int x, int y, int size_x, int size_y, int spr_no=0, CL_DisplayCard *card=NULL) ``` - virtual void **put\_target**( ``` int x, int y, int spr_no, CL_Target *target) ``` - virtual unsigned int **get\_width**() - virtual unsigned int **get\_height**() - virtual unsigned int **get\_num\_frames**() - virtual bool **is\_video**( ``` CL_DisplayCard *card = NULL) ``` - virtual bool **is\_loaded**( ``` CL_DisplayCard *card = NULL) ``` - virtual bool **convert\_video**( ``` CL_DisplayCard *card = NULL) ``` - virtual bool **convert\_system**( ``` CL_DisplayCard *card = NULL) ``` - virtual void **flush**( ``` CL_DisplayCard *card = NULL) ``` ## MEMBERS WITH DESCRIPTIONS - static CL\_Surface \***load**( ``` const char *resource_id, CL_ResourceManager *manager) ``` ``` Description: ``` This function loads a surface from a resource file (usually a datafile). - static CL\_Surface \***create**( ``` CL_SurfaceProvider *provider, bool delete_provider=false) ``` ``` Description: ``` This function creates a CL\_Surface instance being blitted by a caching blitter. !param - virtual void **reload**() ``` Description: ``` Forces surface to reload surface data from provider. - virtual CL\_SurfaceProvider \***get\_provider**() ``` Description: ``` Returns the surface provider used by this surface. ``` Return value: ``` Surface provider used by this surface. - virtual void **put\_screen**( ``` int x, int y, int spr_no=0, CL_DisplayCard *card=NULL) ``` ``` Parameters: x - x coordinate to draw surface. y - y coordinate to draw surface. spr_no - subsprite number to use. card - Display card to be drawn onto. If NULL it will use the currently selected video card by CL_Display. ``` ``` Description: ``` Draws the surface onto the backbuffer. - virtual void **put\_screen**( ``` int x, int y, float scale_x, float scale_y, int spr_no=0, CL_DisplayCard *card=NULL) ``` ``` Parameters: x - x coordinate to draw surface. y - y coordinate to draw surface. scale_x - scale x multiplyer. scale_y - scale y multiplyer. spr_no - subsprite number to use. card - Display card to be drawn onto. If NULL it will use the currently selected video card by CL_Display. ``` ``` Description: ``` Draws the surface onto the backbuffer - scaling it to a specified size. - virtual void **put\_screen**( ``` int x, int y, int size_x, int size_y, int spr_no=0, CL_DisplayCard *card=NULL) ``` ``` Parameters: x - x coordinate to draw surface. y - y coordinate to draw surface. size_x - width of the image when scaled. size_y - height of the image when scaled. spr_no - subsprite number to use. card - Display card to be drawn onto. If NULL it will use the currently selected video card by CL_Display. ``` ``` Description: ``` Draws the surface onto the backbuffer - scaling it to a specified size. - virtual void **put\_target**( ``` int x, int y, int spr_no, CL_Target *target) ``` ``` Parameters: x - x coordinate to draw surface. y - y coordinate to draw surface. spr_no - subsprite number to use. target - target. ``` ``` Description: ``` Draws the surface to a target. - virtual unsigned int **get\_width**() ``` Description: ``` Returns the width of the surface - virtual unsigned int **get\_height**() ``` Description: ``` Returns the height of the surface - virtual unsigned int **get\_num\_frames**() ``` Description: ``` Returns the number of frames/subsprites in the surface - virtual bool **is\_video**( ``` CL_DisplayCard *card = NULL) ``` ``` Description: ``` returns true if in videomemory on the specified card (null = current dispcard). - virtual bool **is\_loaded**( ``` CL_DisplayCard *card = NULL) ``` ``` Description: ``` returns true if loaded in either video- or system-memory - virtual bool **convert\_video**( ``` CL_DisplayCard *card = NULL) ``` ``` Description: ``` returns true if successfully loaded into videomemory, or already there - virtual bool **convert\_system**( ``` CL_DisplayCard *card = NULL) ``` ``` Description: ``` convert surface to system memory - never fails! (or serious heap usage!) - virtual void **flush**( ``` CL_DisplayCard *card = NULL) ``` ``` Description: ``` completely flushes surface (removes from video/system-memory) ## SEE ALSO All ClanLib API classes can be found in **clanlib (3)**. ## AUTHORS Originally written by Magnus Norddahl \<*mbn@dark.x.dtu.dk*\> and Martin Starch \<*starch@dark.x.dtu.dk*\>. ClanLib is now developed by the ClanLib Development team as an Open Source project. The ClanLib man pages was created using the Perceps documentation system (another excellent piece of Open Source software, available at **http://somewhere.in.the.world.org**). See **clanlib (3)** to find out how to get a full list of contributors and details on how to submit bug reports, comments etc.