---

surface.h

Go to the documentation of this file.

/*
        $Id: surface.h,v 1.1 2001/03/06 15:09:10 mbn Exp $

        ------------------------------------------------------------------------
        ClanLib, the platform independent game SDK.

        This library is distributed under the GNU LIBRARY GENERAL PUBLIC LICENSE
        version 2. See COPYING for details.

        For a total list of contributers see CREDITS.

        ------------------------------------------------------------------------
*/


#ifndef header_surface
#define header_surface

class CL_DisplayCard;
class CL_SurfaceProvider;
class CL_Target;
class CL_ResourceManager;

class CL_Surface
//: Image class in ClanLib.
// <p>This class is used to draw 2D images onto the backbuffer or to a
// <a class="CL_Target">renderer target</a>.</p>
//
// <p>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.</p>
//
// <p>A surface uses a <a class="CL_SurfaceProvider">surface provider</a> 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.</p>
//
// <p>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.</p>
//
// <b>Dynamic surfaces</b>
//
// <p>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.</p>
//
// <p>When constructing your own images, you will most likely find the <a
// class="CL_Canvas">canvas surface provider</a> interesting. This class
// will make it easier to create a custom drawing area where you can draw
// your image.</p>
//
// <p>All surfaceproviders is a <a class="CL_Target">renderer target</a>.
// 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 <a class="CL_Canvas">canvas
// provider</a> will not destroy the image.</p>
//
// <p>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.</p>
{
public:
        static CL_Surface *load(
                const char *resource_id,
                CL_ResourceManager *manager);
        //: This function loads a surface from a resource file (usually a datafile).

        static CL_Surface *create(
                CL_SurfaceProvider *provider,
                bool delete_provider=false);
        //: This function creates a CL_Surface instance being blitted by a caching blitter.

        static CL_Surface *create_dynamic(
                CL_SurfaceProvider *provider,
                bool delete_provider=false);
        //: This function creates a CL_Surface instance being blitted by the dynamic (non caching) blitter.
        //: You don't need to call reload with dynamic surfaces as they do that by themselves. 

        CL_Surface();
        //: Empty constructor, you need to assign a surface to the
        //: CL_Surface object first before it becomes useable

        CL_Surface(
                CL_SurfaceProvider *provider,
                bool delete_provider = false,
                bool dynamic = false,
                class CL_Resource *resource = NULL);
        //: This function creates a CL_Surface.
        //  If dynamic is true, the surface will be a dynamic blitter. If false, it will be a caching blitter.

        CL_Surface(
                const char *resource_id,
                CL_ResourceManager *manager);
        //: Loads a surface from a resource file.

        CL_Surface(const CL_Surface &surface);
        //: Make a copy of an other surface, but share the image data.

        virtual ~CL_Surface();

        operator bool () const;
        //: You can use this operator to check if the surface is
        //: valid, to do that you write something like this: if (surf) {...}

        const CL_Surface& operator=(const CL_Surface& surf);

        void reload();
        //: Forces surface to reload surface data from provider.

        CL_SurfaceProvider *get_provider() const;
        //: Returns the surface provider used by this surface.

        void put_screen(
                int x,
                int y,
                int spr_no=0,
                CL_DisplayCard *card=NULL);
        //: Draws the surface onto the backbuffer.

        void put_screen(
                int x,
                int y,
                float scale_x,
                float scale_y,
                int spr_no=0,
                CL_DisplayCard *card=NULL);
        //: Draws the surface onto the backbuffer - scaling it to a specified size.

        void put_screen(
                int x,
                int y,
                int size_x,
                int size_y,
                int spr_no=0,
                CL_DisplayCard *card=NULL);
        //: Draws the surface onto the backbuffer - scaling it to a specified size.

        void put_target(
                int x,
                int y,
                int spr_no,
                CL_Target *target);
        //: Draws the surface to a target.

        unsigned int get_width() const;
        //: Returns the width of the surface

        unsigned int get_height() const;
        //: Returns the height of the surface

        unsigned int get_num_frames() const;
        //: Returns the number of frames/subsprites in the surface

        bool is_video(CL_DisplayCard *card = NULL) const;
        //: returns true if in videomemory 
        //: on the specified card (null = current dispcard).
        
        bool is_loaded(CL_DisplayCard *card = NULL) const;
        //: returns true if loaded in either video- or system-memory

        bool convert_video(CL_DisplayCard *card = NULL);
        //: returns true if successfully loaded into videomemory, or already there

        bool convert_system(CL_DisplayCard *card = NULL);
        //: convert surface to system memory - never fails! (or serious heap usage!)

        void flush(CL_DisplayCard *card = NULL);
        //: completely flushes surface (removes from video/system-memory)

        CL_Surface(class CL_Surface_Generic *impl);
        class CL_Surface_Generic *impl;
};

#endif

---