View source for Make a custom resource provider

Jump to: navigation, search
You do not have permission to edit this page, for the following reason:
The action you have requested is limited to users in the group: Users.
You can view and copy the source of this page:
Note: This page is a work in progress, targetted at CEGUI v0.8.4

The <code>ResourceProvider</code> is the interface that CEGUI uses to load data files of all kinds -- XML, images, fonts, etc.

If you followed the tutorial, then you are probably already vaguely familiar with the <code>DefaultResourceProvider</code>. The default resource provider requires you to specify certain folders for each kind of resource. When CEGUI needs to acquire a resource, the default resource provider simply tries to fetch it from disk, accounting for differences between Unix-like and Windows systems.

There are a few other resource providers that come with CEGUI, particularly, an OGRE resource provider, and Irrlicht one, which integrate with those systems more tightly.

However, maybe you want to write your own resource provider. Why might you want to do this?

# Maybe you want to limit how CEGUI accesses your filesystem. Perhaps you have some kind of virtual filesystem setup, and you prefer for security reasons to have all filesystem calls go through your interface rather than directly through the C / C++ filesystem API. Maybe you are trying to cope with bugs when handling unicode characters in filepaths on some platforms.
# Maybe you are targetting a platform where the filesystem is a bit unusual -- for instance, in emscripten.
# Maybe you are trying to optimize the resource acquisition process by making it cache all available on-disk resources up front for some scenario, and then serve them fast from buffers to CEGUI after that.

To do this, you simply need to derive from <code>CEGUI::ResourceProvider</code>, and start CEGUI using an instance of that instead of the default. This page is to help explain in greater detail what these overrided methods that you provide should do, what responsibilities they have, when they will be called, etc. And especially, to explain how the ownership of the various involved objects works, so that you can avoid leaking / creating undefined behavior.

== ResourceProvider ==

Here is a synopsis of the <code>CEGUI::ResourceProvider</code> class and its most important methods:

    class CEGUIEXPORT ResourceProvider :
        public AllocatedObject<ResourceProvider>
    {
    public:
        ResourceProvider() { }
        virtual ~ResourceProvider() {}
    
        virtual void loadRawDataContainer(const String& filename, RawDataContainer& output, const String& resourceGroup) = 0;
        virtual void unloadRawDataContainer(RawDataContainer&)  { }
    };

The <code>AllocatedObject</code> template is essentially a CEGUI internal detail related to memory management. You don't need to do anything special as a result of that inheritance -- you can just <code>new</code> objects of this type, or derived from this type, and pass them to CEGUI as an appropriate argument to <code>CEGUI::System::create</code>. CEGUI will take ownership of them and delete them as necessary.

The two most important functions are the two that I picked out -- CEGUI calls these when it wants to load or unload a resource. It expects your resource provider to manipulate these <code>RawDataContainer</code> objects to pass it data.

== RawDataContainer ==

<code>RawDataContainer</code> is somewhat like a stripped-down <code>std::vector</code>, except that it always points to an buffer of type <code>unsigned char</code> and there are no "resize" methods or similar. It is always easy to get / set the size / data pointer of the <code>RawDataContainer</code>, as it is intended that you should manipulate the class to get the semantics that you want.

Synopsis of <code>RawDataContainer</code>:

    class CEGUIEXPORT RawDataContainer :
        public AllocatedObject<RawDataContainer>
    {
    public:
    
        RawDataContainer() : mData(0), mSize(0) {}
        ~RawDataContainer() { release(); }
    
        void setData(uint8* data) { mData = data; }
        uint8* getDataPtr() { return mData; }
    
        void setSize(size_t size) { mSize = size; }
        size_t getSize() const { return mSize; }
    
        void release();
    
    private:
        uint8* mData;
        size_t mSize;
    };

The <code>release</code> function of a <code>RawDataContainer</code> calls <code>operator delete[]</code> on the buffer pointer, unless the buffer pointer is null. If that would cause a problem for you, then the <code>unloadRawDataContainer</code> function is your opportunity to empty the <code>RawDataContainer</code> before it is destroyed so that you can do cleanup in a different way.

== Examples ==

For example: If you are using a C++ function like this to open files,

    typedef unsigned char uchar;
    
    std::pair<uchar *, size_t> open_file(const std::string & file) {
      if (FILE * source = fopen(file.str().c_str(), "rb")) {
        fseek(source, 0, SEEK_END);
        int size = ftell(source);
        fseek(source, 0, SEEK_SET);
    
        uchar * buffer = new uchar[size];
        size_t num_read = fread(buffer, size, 1, source);
        (void)num_read;
        fclose(source);
    
        return std::make_pair(buffer, size);
      }
      throw file_not_found_exception(file);
    }

you can overload <code>loadRawDataContainer</code> like this:

    void myResourceProvider::loadRawDataContainer(const String& filename, RawDataContainer& output, const String& resourceGroup) {
      std::pair<uchar *, size_t> result = open_file(filename);
      output.setData(result.first);
      output.setSize(result.second);
    }

You then don't need to override <code>unloadRawDataContainer</code>, as CEGUI will call <code>delete[]</code> later on its own. CEGUI owns the buffer that you loaded in this case.
However, if you implemented <code>open_file</code> using <code>malloc</code> instead of <code>new[]</code>, you will get undefined behavior. Or even, if you compiled your project with one compiler and CEGUI with a different compiler, you may have problems if their memory allocation implementations are not compatible.

If YOU want to own the buffer and not have CEGUI take ownership of it, you might do it like this instead:

    typedef unsigned char uchar;
    
    std::vector<uchar> open_file(const std::string & file) {
      if (FILE * source = fopen(file.str().c_str(), "rb")) {
        std::vector<uchar> buffer;
    
        fseek(source, 0, SEEK_END);
        int size = ftell(source);
        fseek(source, 0, SEEK_SET);
    
        buffer.resize(size);
        size_t num_read = fread(&buffer[0], size, 1, source);
        (void)num_read;
        fclose(source);
    
        return buffer;
      }
      throw file_not_found_exception(file);
    }

I'll assume, for sake of exposition, that as a member of the resource provider, or somewhere else available to you, you have a variable <code>std::map<std::string, std::vector<uchar>> cache_</code> that keeps track of loaded files for the resource provider. Then your resource provider implementation might look like this:

    typedef std::map<std::string, std::vector<uchar>> file_map;
    
    std::vector<uchar> & myResourceProvider::load_helper(const std::string & filename) {
      file_map::iterator it = cache_.find(filename);
      if (it != cache_.end()) {
        return it->second;
      }
      cache_[filename] = open_file(filename);
      return cache_[filename];
    }
    
    void myResourceProvider::loadRawDataContainer(const String& filename, RawDataContainer& output, const String& resourceGroup) {
      std::vector<uchar> & data = load_helper(filename);
      output.setData(&data[0]);
      output.setSize(data.size());
    }
    
    void myResourceProvider::unloadRawDataContainer(RawDataContainer & output) {
      // Make sure cegui doesn't try to delete a buffer owned by our vector!
      output.setData(0);
      output.setSize(0);
    }
    
[[Category:HowTo | ]]
Return to Make a custom resource provider.
Retrieved from "http://cegui.org.uk/wiki/Make_a_custom_resource_provider"
View source for Make a custom resource provider

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Main

Community

Documentation

Tools
